Themis SPARC 10MP Software Manual 





Version2.0— March 20, 1996 





‘Themis Computer—Rest of Weld 
1314S Lareliew Come 1, Rue Des Eos 
ZA. De Mayencia 
Sahi0Giere, France 
Phone 3376 594051 
Fac 38 7643000 





©Copyright 1995 Themis Computer Inc. 


All rights reserved. No part of this work may be reproduced in any form or by any 
means without prior written permission by Themis Computer. 


Restricted Rights Legend: Use, duplication or disclosure by the US government 
is subject to restrictions as set forth in subparagraph (c)( 1 (ii) of the Rights in Tech- 
nical Data and Computer Software clause of DFARS 252.227-7013 (October 

1988) and FAR 52.227-19 (June 1987). 


The information in this document has been carefully checked and is believed to be 
accurate. However, Themis Computer assumes no responsibility for inaccuracies. 
Themis computer retains the right to make changes to this document at any time 
without prior notice. Themis Computer does not assume any liability arising from 
the application or use of this document or the produets(s) described herein. 


UNIX™ is a registered trademark of AT&T 
OPENLOOK™ is a registered trademark of AT&T and Sun Microsystems 
SOLARIS™ is a registered trademark of Sun Microsystems 
SPARC™, SPARC 1OMP™ are registered trademarks of SPARC International 
The following are trademarks of their respective companies and organizations. 
Themis Computer disclaims any responsibility for specifying which marks are 
owned by which companies and organizations: 
Advanced Micro Devices (AMD), ANSI, Centronics, IEEE, Intel, 
ISO, Ethemet, Fujitsu, JEDEC, Level One Communications, Mbus, 


NewBridge, NICE, SBus, SCSI, Signetics, SGS Thompson Micro- 
electronics, Sun Microsystems, VMEbus, Zilog 









Table of Contents 





1: How to Use This Manual... 
LL: Intended Audience 
Organization 
1.3: In Case Of Difficulties. 
2: Installing the SPARC 10MP Software 
2.1: Installing THEMIS vme 
2.2: Detailed Installation... 
2.3: Removing THEMISvme... 
2.4: Installing THEMISvme On Diskless or Dataless Clients. 
2.5: Installing the Sample Drivers . 
2.6: Sample Installation of THEMISvme 
2.7: Sample Installation of the Sample Drivers 
3: Using the VME Interface... 
3.1: Read/Write Test 
3.2: mmap Tes 
3.3: DVMA (slave mode acce: 
3.4: Interrupts Test 
3.5: DMA Test... 
4; Writing Programs for the VMEbus 
4.1: Solaris 2.x Device Hierarchy 
4.2: Features of the VMEbus 
43: Configuring the Software Interface of Themis SPARC 10MP 
4.4: Accessing the VMEbus from Solaris 
4.4.1: Using Read/Write .. 







































4.4.4: Performing a Slave Mode Access to Another VME Board 
4.4.5; Advanced Features of the VMEbus Interface... 


5: Writing VME Device Drivers. 
5.1: Solaris 2.x Device Hierarchy .. 
5.2: Features of the VMEbus 





5.3: Configuration Files for VME Device Drivers 
5.4: Probing devices, 
5.5: Registering Interrupts 
5.6: Allocating DVMA Space. 
5.7: Mapping VMEbus Space... 
5.8: Driving Devices Without Writing Device Drivers 
6: SPARC IOMP Programmers Guid 
6.1: Introduction... 
6.2: Overview of VME Interface Under Solaris | 
6.2.1: VMEbus Nexus Driver 
Utility Drivers 
Sample Drivers 
7: Advanced Configuration of 1OMP. 
7.1: Disabling VMEbus Interrupts. 
7.2: Isolating Boards from VMEbus SYSRESET 
7.3: Handling Data Mismatch Over the VMEbi 
7.4: Handling VMEbus Lock-Up Problems 
7.5: Configuring VMEbus Release Mode. 
7.6: Installing Solaris 1.x Patches on Diskless Clien 
7.7: Removing NEXUS Driver. 
7.8: Determining Speed of MBus Modules 
7.9: Memory Error Message 
7.10: VME Bus Interrupt Problem. 
7.11: 1OMP OBP PROM 
7.12: New IOMP OBP PROM Reset 
7.13: Using TTYC OBP PROM 
8: Sample Device Drivers... 


































How to Use This Manual 1 





he Themis Computer SPARC 10MP is a SPARC-based single-board 

VMEbus computer, The software interface for the SPARC 10MP is 

transparently implemented under Solaris 1.x and Solaris 2.x and is 
compatible with Sun’s SPARCstation 10 workstation, Themis Computer has 
also developed custom software that enables software programmers to 
effectively use the powerful features of the SPARC LOMP. 


Intended Audience 


The custom software containing programs, documentation and packaging, is 
targeted for different kinds of software users: 


‘+ System Administrators who install the software and perform the necessary 
software configuration, 





‘+ Users who perform day-to-day operations on SPARC 10MP systems. 

‘* Application programmers who write user-level programs that utilize tie 
‘VMEbus interface provided under Solaris. 

‘System programmers / device driver writers who develop kernel-level 
device drivers for VMEbus devices. 


Some of these functions overlap one another. The basic concepts required for 
many of these functions are common. This manual is structured around the 
basic concepts of using a VMEbus system. 





1.2 Organization 
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This document is oranized in chapters that focus on a specific functional use of 
the VMEbus software interface. i 


+ Chapter 1, How to Use This Manual: contains a brief overview of this 
document and its organization. 


* Chapter 2, Installing the SPARC 10MP Software: contains instructions on 
installing the many parts of the software interface on a Solaris system. 


* Chapter 3, Using the VME Interface: is intend 4 for users of SPARC 10MP. 
systems. It provides instructions on using the various user level programs 
provided by Themis Computer. These programs could be used to test the 
various features of the VME interface. The programs themselves are 
Provided along with the source code and can be modified by the users of 
the system. The programs can be found in the ‘example’ subdirectory. 


* Chapter 4, Writing Programs for the VMEbus: is intended for programmers 
who are not familiar with the Solaris architecture and the concepts of the 
VMEbus. The document discusses the features of Solaris drivers and 
VMEbus devices as they pertain to the Themis SPARC 10MP product and 
provides tips on writing programs to utilize the different features of the 
VMEbus. 


+ Chapter 5, Writing VME Device Drivers: is intended for systems 
Programmers writing device drivers for VMEbus devices. The guide 
Provides basic information on VMEbus specific features that influence the 
design of drivers for VMEbus devices. The guide also contains tips on 
programming VMEbus devices without writing custom device drivers, 


+ Chapter 6, Programmers Manual: contains extensive information useful to 
experienced programmers who would use the SPARC 10MP under Solaris 
Operating Environment. 

‘* Chapter 7, Advanced Configuration of SPARC 10MP: the SPARC 10MP 
product provides powerful advanced features like generating a SYSRESET 
on the VMEbus, configuring the interrupt mechanism etc, Themis Computer 
periodically issues Technical Notes that detail these interfaces and ways to 
access them. These Technical Notes have been put together in this 
document. 
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* Chapter 8, Sample Device Drivers: these drivers have been written to 
illustrate features particular to VMEbus device drivers. These drivers are 
Provided along with the source code. The manual pages for the drivers 
contain sample programs that use the drivers. 


+ Appendix A, Manual Pages: online manual pages have been added for all 
drivers provided by Themis Computer. Manual pages are available for the 
standard nexus and DMA drivers as well as the sample drivers, 


1.3 In Case Of Difficulties 


Rev, Date: 3/19/96 


If the LOMP does not behave as described or if you encounter difficulties 
stalling or configuring the 10MP either standalone or as part of your 
VMEbus system environment, please call Themis Computer technical support 
at 510-252-0870, fax your questions to 510-490-3529, or e-mail them to 
support@themis.com. You can also contact us at our web site: www. themtis.com. 
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Installing the SPARC 10MP Software 2 





he software interface for SPARC 10MP is distributed as a software 

a i package for Solaris 2.x systems. The software package is named 
THEMISvme and can be installed and removed like other standard 

Solaris software packages, by using the pkgadd and pkgrm commands. 


Installing THEMISome 


‘The THEMISvme package is distributed on standard media and can be 
installed directly from the media. To install the package, place the installation 
media in the appropriate slot and execute this comman 





# pkgadd -d <media name> 
where <media name> is the name of the media on your system. 


‘The pkgadd command will copy the contents of the package to the appropriate 
directories and perform the necessary installation. After the command 
completes, the system has to be rebooted for the new software to be 
operational 


The THEMISvme package can be installed safely on a system that already has 
previous version of SPARC 10MP drivers installed. The previous versions of 
the drivers will be saved; the saved files will be restored when the 
THEMISvme package is removed. 





The sample drivers contained in the package will be copied to the directory 
/opt/THEMISvme/drv. The user may choose to install these drivers by 
‘executing a script provided for that purpose. The sample drivers are not 
required for the normal operation of the SPARC 10MP system. 


2.2 Detailed Installation 
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During the course of installation, pkgadd will prompt the user for input on 
optional configuration. The first prompt will request the user to choose the 
packages to be installed: 


The following packages are available: 
1 THEMISvme Themis SPARCLOMP VME Drivers 
(sparc) LOMP 2.0 


Select package(s) you wish to process (or ‘all’ to process 
all packages). (default: all) [?,??,q]: 


Simply press <RETURN> to choose the THEMISvme package for installation. 
‘The next input concerns the directory where the VME drivers will be placed: 


Themis SPARC1OMP VME Drivers 
(sparc) 1OMP 2.0 
Themis Computer 


Where should the driver objects be installed {/kernel/drv] 
(?.q@) 


It is recommended that you choose the default input, /kernel /drv. If you 
choose to install the drivers in a directory other than /kernel/drv or 
/ust/kernel/drv, you may have to edit the /etc/system file to inform the 
kernel of the search path for driver object files. 


The next prompt from pkgadd is: 
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The next prompt from pkgadd is: 


‘This package contains scripts which will be executed with 
Super-user permission during the process of installing 
this package. 


Do you want to continue with the installation of this 
package [y.n,?] 


The THEMISvme package contains custom scripts for easy installation of the 
package with minimal intervention from the user. These scripts need to be 
executed with super-user permission, Enter y to continue with the installation 
of the package. 


After these prompts, pkgadd will proceed with copying the files to the system 
and installing the necessary drivers. At the end, you should see this message: 


Installation of <THEMISvme> was successful. 


If for any reason, the installation is not successful, please note down the error 
‘messages on the screen and contact Themis Technical Support. 


2.3 Removing THEMISume 
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If you want to remove the software interface of SPARCIOMP for any reason, 
you can execute the pkgem command to remove the THEMISvme package: 


# pkgrm THEMISvme 


pkgrm will remove all the files contained in the package. The original contents 
of VME drivers before the package was installed will be restored. 
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2.4 Installing THEMISvume On Diskless or Dataless Clients 


Currently, most of the software interface contained in THEMISvme can be 
installed on diskless and dataless client systems. On these clients, the VMEbus 
drivers will be copied and installed correctly. The header files and manual 
pages will be placed in the /opt/THEMISvme directory. 


2.5 Installing the Sample Drivers 


The /opt/THEMISvme/drv directory contains the source and binary versions 
of the sample device drivers in subdirectories ‘src’ and ‘bin’. The subdirectory 
‘themis’ includes header files that need to be copied to the 
/ust/include/themis directory on the system. The example programs rely on 
these header files. 


To compile the drivers, you need to go into the subdirectory ‘sre’ and type 
‘make’. The compiled driver binaries will be placed in the ‘bin’ subdirectory. 


To install the drivers, all the files in the ‘bin’ directory need to be placed in a 
directory that usually contains driver modules. (Typically this may be 
/kemel /drv or /usr/kernel/drv.) Then the drivers can be installed on the 
system by using the add_drv command, 


Before using the drivers, you need to create files under the /dev directory. 
These files are symbolically linked to the actual device files under the /devices 
directory tree. 


Scripts have been provided to perform the above tasks. The install sample 
scripts copies the drivers (as they are packaged) to the /kernel/drv directory. 
It then installs the drivers on the system, creates the files under /dev and 
copies the header files into the /usr/include/themis directory. The 

remove sample script undoes all the installation done by the install script. You 
are strongly urged to carefully review the scripts before executing them. 


If you need to make any changes to the drivers, you need to compile the 
drivers after the changes. After that you can copy the newly built driver object 
files to the /kernel/drv directory. You can install the new drivers on the 
running system by first executing the rem_drv command and then the add_drv 
command. 
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The remove sample script removes the sample drivers from the running 
system. The script deconfgures the drivers from the kernel and remove the 
driver object files from the /kernel/drv directory. 


2.6 Sample Installation of THEMISume 
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‘The contents of the screen during an installation of the THEMISvme package 
are given below. Input by the user appears in italics. 


# pkgadd -d /dev/rmt/0 


The following packages are available: 
1 THEMZSvme Themis SPARCLOMP VME Drivers 
(sparc) 10MP 2.0 


Select package(s) you wish to process (or ‘all’ to process 
all packages). (default: all) (?,??,q]: all 


Processing package instance <THEMISvme> from /dev/rmt/0 


Themis SPARCLOMP VME Drivers 
(sparc) 10MP 2.0 
‘Themis Computer 


Where should the driver objects be installed [/kernel/drv] 
{?.ql /kernel/drv 
#¥ Processing package information. 
## Processing system information. 

12 package pathnames are already properly installed. 
## Verifying disk space requirements. 
## Checking for conflicts with packages already installed. 


The following files are already installed on the system 
and are being used by another package: 

(kernel /érv/vme 

(kernel /drv/vmemem 


Do you want to install these conflicting files (y.n,?.q] y 
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This package contains scripts which will be executed with 
Super-user permission during the process of installing 
this package. 


Do you want to continue with the installation of this 
package [y.n.?] y 


Installing Themis SPARCLOMP VME Drivers as THEMISvme 


4% Executing preinstall script. 
Saving current files ... 

( verifying class <none> | 

## Installing part 1 of 1. 

l verifying class <devlink> ] 

(kernel /drv/vme 

(kernel /érv/vmedma 

(kernel /drv/vmedma.con£ 

(kernel /drv/vmemen 

( verifying class <drv> } 

[ verifying class <include> } 

[ verifying class <manpage> | 

## Executing postinstall script. 

Adding following devices to //etc/name_to_major 
vmemem 67 

Adding following devices to //etc/name_to_major 
vmedma 95 

Adding following permissions to //etc/minor_perm 
vmemem:* 0666 bin bin 

vmedma:* 0666 root sys 


It will be necessary to do a reconfiguration reboot after 
driver installation. As soon as possible, execute ‘reboot 
- -r' to reboot. The new vme drivers will not be 
functional till a reboot is done. 


Installation of THEMISvme was successful, 


The following packages are available: 
1 THEMISvmeThemis SPARCIOMP VME Drivers 
(sparc) 10MP 2.0 
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Select package(s) you wish to process (or ‘all’ to process 
all packages). (default: all) (?,22.a]: ¢ 





2.7 Sample Installation of the Sample Drivers 
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The screen output when the install sample script is run on a system is 
included below. ( Characters typed by the user appear in italics.) 

# cd /opt/THEMISvme/drv 

# ./install.sample 


This script installs the sample device drivers for Solaris 
2.4 to use the VMEbus interface on the Themis LXE+/564. 


The script creates symbolic links under /dev for the 
device special files. 


If you want to proceed, type y or ¥. Otherwise, press any 
other key to abort. 


¥ 

+++ Replacing vmeintr interrupt driver 
Replacing vmedvma DVMA driver 

Installing new drivers 

Creating new devices 

Copying header files 


Installation completed. 





Installation Script for 
‘Themis SPARC 10MP Solaris 2 
sample device drivers 
Version 1.2 
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1 Themis systems, the power supply to the board is drawn through the 
VME chassis. If you are able to power the board up and run 
diagnostics, it is very likely that the basic VMEbus interface is 

functioning as intended. To verify the full functionality of the VMEbus 

interface and to illustrate the use of the sample device drivers, Themis 
provides a number of test programs. These are provided along with the source 
code. 





This document gives a brief introduction to the different test programs 
provided by Themis Computer. Most of the test programs have a similar user 
interface. The reader may like to read the tutorial on the software interface 
provided by Themis to gain a fuller understanding of the concepts behind the 
test programs. 


Alll the example programs (with the exception of the sample DMA program) 
work the same way on Solaris 1.x and Solaris 2.x systems. 
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3.1 


B44 


Read/Write Test 


This test performs simple read/write operations on VMEbus address space.The 
test requires the presence of memory space accessible over the VMEbus. 
Usually this space is provided by a memory card or through slave access to 
another VME board. Invoking the test program provides you with a command 
shell; from this shell you can execute any of the different tests. 


A test session using the read/write test is given below. User input appears 
within angled brackets. The test system had a memory board on the VMEbus. 
The memory board was installed as an A32D32 board, with address range 
from 0x72a00000 to 0x749fffff. 


# <./yme_rw> 
Themis Computer - VME read/write test program 


Enter command, h for help : <h> 

@ adrs(, length] display memory 

h > print this list 

madrs{,value]  - modify memory 

q = quit program 

z adrs{,length] - zero memory 

3 mode - set VME access mode 
Ox0L = A32D32, 0x02 = A32D16 
Ox1l = A24D32, Oxi2 = A24D16 
Ox21 = A16D32, 0x22 = Al6D16 
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Enter command, h for help : <s 1> 
WME file /dev/vme32d32 successfully opened. 


Enter command, h for help : <z 0x72a00000 0x1000>" 
Done. 


Enter command, h for help : <d 0x72a00000 0x20> 


0x72a00000: 00000000 00000000 acccccd0 o0000000 
0x72a00010: 90900000 90000000 o0000000 90000000 


Enter command, h for help : <m 0x72a00000 0x20> 





0x72a00000: 00000000 2 <0> 
0x72a00004: 00000000 2 <I> 
0x72a00008: 00000000 2 <a> 
0x72a0000c: 00000000 ? <i> 
0x72a00010: 00000000 2 <a> 
0x72a00014: 00000000 2 <S> 
0x72a00018: 00000000 2 <6> 
0x72a0001c: 00000000 2 <> 


Enter command, h for help : <d 0x72a00000 0x20> 
0x72a00000: 00000000 00000001 00000002 00000003 
0x72a00010: 00000004 00000005 00000006 00000000 


Enter command, h for help : <d 0x72a00020 0x20> 
0x72a00020: 00000000 00000000 00000000 00000000 
0x72a00030: 00000000 00000000 o0000000 00000000 
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3.2 mmap Test 
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Enter command, h for help : <d 0x74a00000 0x10> 


0x74a00000: 5 
Bus Error: received signal :10 


Enter command, h for help : <d 0x73a00000 Ox10> 
0x73a00000: 00000000 00000000 09000000 doc00000 


Enter command, h for help : <q> 


This test maps a chunk of VMEbus address space into user memory and 
performs a read or write operation on it. The test is very similar to the 

read /write test. However, instead of using read() and write() system calls, the 
test maps the specified region into user memory using mmap(). This space can 
then be accessed like any other space in user memory. 


The test require the presence of memory space accessible over the VMEbus. 
Usually this space is provided by a memory card or through slave access to 
another VME board. Invoking the test program provides you with a command 
shell; from this shell you can execute any of the different tests, 


A test session using the mmap test is given below. User input appears within 
angled brackets. The test system had a memory board on the VMEbus. The 
memory board was installed as an A32D32 board, with address range from 
0x60000000 to Oxé61 ffffff. 
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# <./vme_mmap> 
Themis Computer - VME mmap test program 


Enter command, h for help : <h> 


dadrs(,length] - display memory 
b - print this list 

m adrs(,value] - modify memory 

a = quit program 

z adrs{,length] - zero memory 

s mode set VME access mode 


0x01 


= A32D32, 0x02 = A32D16 
Oxil = A24D32, Oxl2 = A24D16 
Ox21 = A16D32, 0x22 = AL6D16 


Enter command, h for help : <s 1> 
WME file /dev/vme32d32 successfully opened. 


Enter command, h for help : <z 0x60000000 0xi000> 
Done. 
Enter command, h for help : <d 0x60000000 0x20> 


0x60000000: 00000000 00000000 00000000 00000000 
0x60000010: 00000000 00000000 00000000 o0000000 


Enter command, h for help : <m 0x60000000 0x20> 





0x60000000: 00000000 2 <0> 
0x60000004: 00000000 2 <i> 
0x60000008: 00000000 2 <2> 
0x6000000e: 00000000 2 <> 
960000010: 00000000 2 <4> 
0x60000014: 00000000 2 <S> 
0x60000018: 00000000 2 <b> 
0xs000001c: 00000000 2 <> 
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Enter command, h for help : <d 0x60000000 0x20> 


0x60000000: 00000000 00000001 00000002 00000003 - 
0x60000010: 90000004 00000005 00000006 00000000 


Enter command, h for help : <d 0x60000020 0x20> 


0x60000020: 00000000 00090000 00000000 00000000 
0x60000030: 00000000 00000000 d0000000 00000000 


Enter command, h for help : <d 0x62000000 Oxlo> 


0x62000000: 
Bus Error: received signal :10 


Enter command, h for help : <d 0x61000000 Oxlo> 
061000000: 00000000 00000000 00000000 00000000 


Enter command, h for help : <g> 


3.3. DVMA (slave mode access) test 


‘Memory on the SPARCIOMP board can be accessed from another board on the 
VMEbus chassis. This type of access is called slave mode access. Slave mode 
access under Solaris is tied to the concept of Direct Virtual Memory Access 
(DVMA). DVMA is a facility present on SPARC hardware that allows a device 
driver to specify virtual addresses rather than physical addresses for a DMA 
operation. The kernel maintains a map that specifies the correspondence 
between the DVMA address and the physical memory. 
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This section describes the many features of the software interface provided by 
Themis Computer. The features provide the system programmer with 
powerful ways of accessing the VMEbus from the Solaris Operating System 
environment. Themis Computer has developed many sample programs that 
illustrate the ways of using the software interface provided by Themis. These 
programs are available with the source code. These programs can be used to 
test the configuration of a VME system; they can also be used as example 
programs for the use of the different features provided by the software 
interface. 


The following subsections introduce the concepts of accessing the VMEbus 
from user programs. Each concept is fully illustrated by a sample program. The 
reader is strongly encouraged to review the sample programs while reading 
this guide. The programs can be freely modified in any way that the user 
wants to. For more information on running the sample programs, please 
consult the document named "Using the VME interface’. The reader may note 
that though the examples in this section use VMEbus memory boards, the 
usage can be extended to any type of VMEbus board. 


‘The DVMA test allocates a DVMA region in memory and performs read/write 
operations on the region. The user interface of this test is quite similar to that 
of the mmap test except that instead of physical addresses, offsets into the 
DVMA region are used. 


It is quite illustrative to use another system to perform slave mode access to 
the DVMA region. Usually the DVMA test is run on one machine; on another 
machine on the same VMEbus chassis, the mmap test is run. Both tests can 
then access the same region in memory. 


In the following example, ‘slave’ is the system that allocates a DVMA region; 
‘master’ is the system that performs a slave mode access to the region. The 
slave-base-address of the slave system is assumed to be 0x0; the master’s slave~ 
base-address needs to be such that the slave address regions of the two 
machines don’t overlap. In this case the master’s slave base address is 
0xa00000. 


Rev. Data: 3/20/96 Using the VME Interfice 319 





(On slave: 
# <./vme_dvma> 
‘Themis Computer - VME DVMA test program 


Enter command, h for help : <h> 


@ offset(, length] - display memory 
h - print this list 

m offset[,value] - modify memory 

q - quit program 

2 offset[,length] - zero memory 

8 size - set up DVMA region 
£ - free DVMA region 


Enter command, h for help : <s 0x2000> 
id= 0x0, addr= Ox2ac8, sz= 0x2000 


(The addr is used to access this region from another 
machine) 
Enter command, h for help : <d 0 0x20> 


9207bEfe 4000779b EOZ7bEEc 81c7e008 
9180008 9de3b£a0 b4100019 92100018 


00000000) 
0x0000002 





On master: 
# <./vme_mmap> 
Themis Computer - VME test program 


Enter command, h for help : <s 0xll> 
VME file /dev/vme24d32 successfully opened. 
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Enter command, h for help : <d Ox2ac8 


0x00002aca: 9207bEfc 4000779b £027bEEC 
0x00002ad8: 91¢80008 9de3bfa0 b4100019 


(ote that the contents of the region 
viewed 
from different machines.) 


Enter command, h for help : <z Ox2ac8 
Done. 


Enter command, h for help : <d Ox2ac# 


0x00002ac8: 00000009 00000000 oooc0000 
0x00002ad8: 00000000 00000000 od000000 


Now on slave: 


Enter command, h for help : <d 0 0x20> 


0x00000000: 00000000 00000000 09000000 
0x00000010: 00000000 00000000 00000000 


(Again, we can see that the two systems share the sa 


0x20> 


81c7e008 
92100018 


are the same when 


0x20> 


0x20> 


90000000 
90000000 


00000000 
00000000 


me view 


of the contents of the region. Now we will modify the contents 


starting from offset 0x20.) 
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Enter command, h for help 





0x00000020: 0002e884 4 
0x00000024: 0002e88¢ ? 
0x00000028: 0002¢898 ? 
0x0000002c: 0002e8a0 ? 
0x00000030: 0002e8a8 ? 
0x00000034: 0002e8b4 ? 
0x00000038: 0002e8c4 2 
0x0000003c: 0002ea58 ? 
0x00000040: 0002ea5c ? 
0x00000044: 0002ea68 2 
0x00000048: 0002ea78 ? 
0x0000004c: 0002eaa4 ? 
On master: 

Enter command, h for help 


0x00002a 
0x00002a£8 
0x00002b08: 






: <d Ox2ae8 


90000001 00000002 00000003 
00000005 00000006 00000007 
90000009 00000010 00000011 


0x20> 


0x30> 


00000004 
00000008 
o002eas4 


(We can see that the master can view the modified contents.) 
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dvmatest allocates a small Direct Virtual Memory Access Region on the 
VMEBus address space and then writes the alphabetical characters into it. 
vdma is a general purpose program that allocates and frees DVMA regions. 
This test uses the vmedvma driver to set up a Direct Virtual Memory Access 
Region on the VMEBus address space. This memory can then be accessed 
either from the same machine or from another machine on the VME system 


simulmaster and simulslave are programs that illustrate the simultaneous 
access from multiple systems of a DVMA region allocated on one system. 
simulslave is run first; it allocates a DVMA region of 10 pages and outputs the 
region's size and virtual address. These are given as input to the simulmaster 
program on another system. The two programs try to access the same VMEBus 
address in alternating fashion. Suspending one of the programs will lead the 
other to stop; resuming the suspended program will make the other program 
start again, 


3.4 Interrupts Test 


This test requires the presence of two processor boards on the VME chassis. 
One of the boards is designated as the 'test initiator’ and the other as the ‘test 
executor.’ Typically, a program on the ‘test executor’ machine registers to 
process a particular interrupt. A program on test initiator machine is used to 
generate an interrupt on the VMEBus; this interrupt will be received by the test 
executor machine. The vmeintr driver should be installed on both the 
machines. The interrupts that can be received are specified by the 
configuration file for the vmeintr driver. ( usually /kernel/drv/vmeintr.conf) 


Output from a test session is included below. In this case, the following 
interrupts were configured in the vmeintr.cont file: vector 0x80, priority 2 and 
‘vector 0x81, priority 3. 


On test executor: 
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# <./vme_inte> 
Themis Computer - VME interrupts test program 


Enter command, h for help : <h> 
@ vector priority- enable an interrupt 

s vector priority- send an interrupt 

w - wait for an interrupt 

a - disable (mask) an interrupt 
h - print this list 

a - quit program 


Enter command, h for help : <e 0x80 2> 
Set up to receive interrupt, vector : 0x80, priority: 2 
Enter command, h for help : <w> 

Waiting for interrupt. You have 30 seconds to generate it. 
No interrupt received in the last 30 seconds 

Enter command, h for help : 


(The wait timed out after 30 seconds because no interrupt was 
generated.) 


On test initiator: 
# <./vme_inte> 

‘Themis Computer - VME interrupts test program 
Enter command, h for help : <s 0x80 2> 


Enter command, h for help 


Now on test executor: 
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Enter command, h for help 


<u> 


Waiting for interrupt. You have 30 seconds to generate it. 


Received interrupt; vector 


Enter command, h for help 


(You may see that the wait returns immediately because an interrupt was 


already pending.) 


Enter command, h for help 


An interrupt is enabled already. 


Enter command, h for help 


Enter command, h for help 


Set up to receive interrupt, 


Enter command, h for help 


0x80, priority: 


<e 0x81 3> 


<a> 


<e 0x81 3> 


vector 


<> 


0x81, 


The roles of the test initiator and the test executor can be 


reversed at any time. 
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Disable it first. 


priority: 


3 


3:25 


a 





3.5 DMA Test 
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Direct Memory Access is the process by which a device takes control of the bus 
and performs data transfers to (and from) main memory or other devices. The 
device does this work without the help of the CPU. DMA transfers occur at 
significantly higher speeds as compared to normal transfers using 
read()/write() or mmap(). 


‘On Themis SPRACIOMP platforms, DMA access to the VMEbus is provided by 
the Fujitsu MBus to VMEbus Contolled. The vmedma driver provides user 
access to the DMA features of the MVIC controller. Using the ioctl interface 
provided by the driver, the user program can utilise the DMA engine and 
achieve high rates of data transfer. 


Typically a DMA transfer occurs between memory and the VMEbus, The 
memory location is specified by a user virtual address that is usually obtained 
via mailoc() or mmap(). The VMEbus location is specified by a physical 
VMEbus address. The VMEbus address space does not have to be mapped into 
user memory. 


In addition to transfers between VMEbus and memory, the vmedma driver 
also supports transfers from memory to memory and VMEbus to VMEbus. 
Depending on the capabilities of the hardware platform, these transfers may be 
emulated in software, 


The dmatest program provides a way to test the DMA mechanism on the 
SPARCIOMP product. To illustrate the high efficiency of DMA transfers, this 
progam is controlled by command line arguments, unlike the other test 
programs which provide a command shell. 
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The usage of the program is: 


dmatest [-hold] [-release] [-source <addr>] [-dest <addr>] [-size <count>] 


loops <loop_count>] [-bit] [-retain] 


[-noblock] [-check] [-first] [-help] 


By default, the program performs a transfer from memory to memory, 
unless the source and /or -dest options are specified. 

When -source or -dest is used, <addr> is a VMEbus address 

specifier as follows: 


{al64,32,24) [d{64,32,16}:I[<addehi>.J<addrlo> 


<addrhi> is only required when a64 addresses are used. 


To test VME to memory transfers, specify the 

VMEbus source address with the -source <address> option. : 
To test memory to VME transfers, specify the -dest <address> options 
For VME to VME transfers , specify 

both -source and -dest, and for memory to memory transfers, 

specify neither. The default address mode is A32D32. 


The default transfer size is 0x10000 bytes, unless the -size option 


is specified. The default number of transfers is 10, unless the 
-loops option is specified. 
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Other options are: 


= size + set size of each transfer 
- loops ~ set # of loops to run - 
-bit - use block mode transfer 

= retain ~ use a retained buffer 

= noblock ~ nun in non-blocking mode 

~ check ~ check results every loop (not valid with -noblock) 
- first - only print first error in buffer 

help ~ print the usage 

-hold ~hold the DMA engine ~ no other args are valid 

= release - release the DMA engine ~- no other args are valid 


The -retain options request the program to lock the user addresses 
in memory. This options makes repeated transfers more efficient. 


A test session using the dmatest is given below. 
‘The test system had a memory board on the VMEbus, The memory 
board was installed as an A32D32 board, with address range 

from 0x72a00000 to Ox7494ftff 


# ./dmatest -help 
Usage: 
-/dmatest (-hold] [-release] [-source <addr>] [-dest <addr>] 
(-size <count>] [-loops <loop_count>) [-blt] [-retain] 
[-noblock] [-check] [-first] [-help] 





When -source or -dest is used, <addr> is a VMEbus address specifier, 
as follows: 


(a(64,32,24)] (4 (64,32, 16}: ] [<addrhi>. ]<addrlo> 
<addrhi> is only required when a64 addresses are used. 








50000000 ~ VMEbus A32 address 0x50000000 
a24di6:500201£0 ~ VMEbus A32D16 address 0x500201£0 
a64432:10.500201£0 = VMEbus A64D32 address 0x10500201£0 


Other options are: 
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hold - hold the DMA engine (no other options valid) 

release - release the DMA engine (no other options valid) 

size ~ set size of each transfer 

-loops - set # of loops to run 2 
sble - use block mode transfer 

retain - use a retained buffer 

-noblock - run in non-blocking mode 

~check - check results every loop (not valid with -noblock) 

-help - print the usage 


# 

# ./dmatest -dest 0x72a00000 -size 0x1000 -loops 100 
Starting 100 loops 

Don 
Copied 400.000 KB in 0.180 seconé: 
* 

#  ./dmatest -dest 0x72a00000 -size 0x1000 -loops 100 -retain 
Starting 100 loops 

Done. 

Releasing retained buffer (id £c252208) 

Copied 400.000 KB in 0.092 seconds: 4347.826 KB/sec 

# 

# ./dmatest -source 0x72a00000 -Lloops 1000 

Starting 1000 loops 

Done. 

Copied 64000.000 KB in 10.179 seconds: 6287.455 KB/sec 

* 

# ./dmatest -source 0x72a00000 -loops 1000 -retain 

Starting 1000 loops 

Done. 

Releasing retained buffer (id £c252c30) 

Copied 64000.000 KB in 8.368 seconds: 7648.184 KB/sec 

* 

# ./dmatest -source 0x72a00000 -dest 0x73a00000 -loops 1009 -retain 
Starting 1000 Loops 

Done. 

Releasing retained buffer (id £c252750) 

Copied 64000.000 KB in 23.509 seconds: 2722.362 KB/sec 

* 





2222.222 KB/sec 
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he software interface of the 10MP is transparently implemented under 
Solaris 1.x (SunOS 4.1.3) and Solaris 2.x. The software interface is fully 
compatible with generic Sundm VME architecture systems. Any VME 
device driver that confirms to the appropriate Solaris Device Driver Interface 
will run unmodified on Themis platforms. 


This guide is intended for system programmers who are not familiar with the 
Solaris architecture and the concepts of the VMEbus. The guide discusses the 
concepts of Solaris drivers and VMEbus devices as they pertain to the Themis 
SPARC 10MP product. The guide is intended as a general introduction of the 
basic concepts of using the Themis SPARC 10MP product under Solaris. The 
guide is not intended as a reference document. The reader may refer to other 
documents for more detailed information. Convenient access to the SPARC 
10MP User Manual and the on-line manual pages for Solaris would be helpful 
while reading this manual. 


Solaris 1.1.1 (SunOS 4.1.3) is Sun’s legacy operating system. The VME drivers 
for Solaris 1.1.1 are provided on tape by Themis Computer. The transparent 
inteeface enables the running of any off-the-shelf application on the SPARC 
10MP. Solaris 2.x family is a new generation of operating system that unifies 
Suns older BSD derived kernel and the newer UNIX SVR4 technology. The 
new operating systems add many new features like Symmetric 
Multiprocessing, Dynamically Loadable Drivers, ete. 


In its current version, this guide focuses on the software interface provided 
under Solaris 2.x. However, except for section 4.1, the material in this guide 
applies to Solaris 1.1.1 systems also. 
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41 Solaris 2.x Device Hierarchy 


Solaris 2.x systems support architecture independence of devices by using a 
layered approach. Each node in the tree structure has a specific device 
function. Standard devices are associated with leaf nodes. The drivers for these 
devices are called leaf drivers. The intermediate nodes in the tree are 
associated with buses, like SBus, VMEbus etc. These nodes are called bus 
nexus nodes and the drivers associated with them are called bus nexus drivers. 
‘The bus nexus driver encapsulates all the architectural dependencies of a 
particular bus. The leaf driver only needs to know the kind of bus it is 
connected to. 


On Themis SPARC10MP systems, the device tree looks like this: 


























sbusmem| | espdma 
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In this diagram, root, iommu, THEMIS,vme and sbus are bus nexus drivers. 
The iommu encapsulates the features of the I/O Memory Management Unit 
found on sundm systems. The vme driver encapsulates all the details of the 
implementation of the VMEbus interface. The vmemem driver, which is a leaf 
driver, only needs to know that it is connected to the VMEbus. 


Solaris, like other UNIX systems, represents devices as special files in the file 
systems, These files are advertised by the device driver and are maintained by 
the drvconfig(1M) program. Usually the special files are created under the 
/devices directory and represent the hardware layout of a particular machine. 
sysdef(1) and prtconf(1) can be used to view the internal device tree, Symbolic 
links are created from the /dev directory to the special files in the /devices 
directory. User programs normally use the files from the /dev directory. 


4.2 Features of the VMEbus 
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‘The VMEbus is an industry standard device interfacing bus that supports 
multiple address spaces. This means that a single VMEbus system can support 
devices that are 16-bit, 24-bit or 32-bit. There are many other features of the 
VMEbus which concern the system programmer. Another peripheral bus 
present in many SPARC platforms is the SBus, 


VMEbus address space is not different from the physical memory space. A 
VMEbus address is indistinguishable from a memory address. Each card on 
the VMEbus has its own address. Usually this address is configurable. The 
address remains the same irrespective of the slot that the card is plugged into, 
In contrast, the SBus is geographically addressed; the address of a card is 
determined by the slot it is plugged into. 


VMEbus supports multiple address spaces. A VMEbus system can support 
either 16,24 or 32 address bits and either 16 or 32 data bits. Some VMEbus 
cards can respond to multiple size of address bits. These cards must be 
configured for the desired access mode. Usually this configuration can be done 
by jumper settings. It is necessary for the device driver developer to specify the 
address space supported by the device in the hardware configuration file. 


‘VMEbus devices are not self-identifying ie. they do not provide information 
themselves to the system. Drivers for VMEbus devices need to have a probe() 
entry so that the kernel can determine if the device is really present. Additional 
information about the device must be provided in a hardware configuration 
file. See driver conf(4) and vme(4) for more information 
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VMEbus interrupts are vectored. When a device interrupts, it provides the 
priority as well as an interrupt vector. The kernel uses the information to 
uniquely identify the interrupt service routine to be called. The hardware 
configuration file must specify each priority-vector pair that the device may 
issue. 


4.3 Configuring the Software Interface of Themis SPARC 10MP 


TThe SPARCIOMP board can be accessed in a slave mode from another board 
on the VMEbus chassis. This type of access requires specifying the slave base 
address and the size of the slave access region of the 10MP board. Distinct 
values can be specified for 24 bit addresses and 32 bit addresses. On a VMEbus 
chassis with multiple boards, each processor board is required to have a non- 
overlapping region for slave mode access. The OBP attribute vme32-slave-base 
and vme-boardid can be used to set the slave base addresses of a 10MP board. 





The OBP attribute VME 32-Slave-base specifies the A32 slave base address, The 
OBP attribute vme-boardid specifies the higher byte of the A24 slave base 
address. i.e. A value of 2 for vme-boardid specifies a value of 0x20 0000 for the 
A24 slave base address. Please refer to section 7 for details on modifying OBp 
attributes. 
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This section describes the many features of the software interface provided by 
Themis Computer. The features provide the system programmer with 
Powerful ways of accessing the VMEbus from the Solaris Operating System 
environment. Themis Computer has developed many sample programs that 
illustrate the ways of using the software interface provided by Themis. These 
Programs are available with the source code. These programs can be used to 
test the configuration of a VME system; they can also be used as example 
Programs for the use of the different features provided by the software 
interface. 


The following subsections introduce the concepts of accessing the VMEbus 
fom user programs. Each concept is fully illustrated by a sample program. The 
reader is strongly encouraged to review the sample programs while reading 
this guide. The programs can be freely modified in any way that the user 
wants to. For more information on running the sample programs, please 
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consult the document named ‘Using the VME interface’. The reader may note 
that though the examples in this section use VMEbus memory boards, the 
usage can be extended to any type of VMEbus board. 


44.1 Using Read/Write 


‘The vmemem driver from Themis Computer enables the user to access any 
VMEbus address from a user program. Depending on the address space used 
by the particular VMEbus card, different devices need to be used. 


Table 4-1. VME Table 









































[ File Address Size | Data Transfer Size | Physical Address Range 
idevivmetéat6 | 16 bits 16 bits ‘Ox0-OxF FFF 
idovivmersa16 | 24 bits 16 its (Ox0-OxF FFFFF 

32 bits 16 bits ‘Ox0-OxF FFFFFFF 
Idevivmeiéd32 | 16 bits 32 bits Ox0-OxF FFF 
Idevivme24d32 | 24bits 32 bits Ox0-OxFFFFFF 
Idevivmes2d32 | 32 bits 32 bits OK0-OxF FFFFFFF 











e.g, to access a VME card that supports 24-bit addresses and 32-bit data 
transfers, the user needs to use the file /dev/vme24d32. 


Using /dev/vmeXXdYY files is very similar to using normal files; the user 
program opens the file, uses the memory address as an offset to Iseek to and 
does a read or write operation at the offset. The ‘offset’ must fall within the 
physical address range of the file that was opened; also there should be a 
VMEbus device that would respond to the address. 


Rov. Dato: 0/19/96 Writing Programs forthe VMtEbus 435 





To access 16 bytes at the VMEbus address 0xa0000, the following code snippet 
can be used: 


int fa; 
int vme_base; 
char buffer(16]; 


if ( ( fd = open( */dev/vme24d32", O_RDWR)) < 0) 
( 
perror("In opening file /dev/vme24d32"); 
return(-1); 
} 


vme_base = 0xa0000; 
if ( seek ( fd, vme_base, SEEK_SET) < 0) 
« 

perror("In lseeking to 0xa000"); 

close( fd); 

return (-1); 


if ( read ( fd, buffer, sizeof (buffer) ) ! 





sizeof(buffer) ) 





perror("In reading 16 bytes"); 
close (fd); 
return(-1); 
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In the above example, if there is no device on the VMEbus at address 0xa0000, 
the VMEbus operation will time-out and the program would receive a SIGBUS 
signal. 

The vmeXXdYY files can also be used to quickly check the proper installation 
of a VME board. e.g. After installing a VME memory board at address 
0x72000000, the user can use od(1) to look at the memory: 


> od -x /dev/vme32d32 +0x72000000 


If the od command displays '0x72000000'_and nothing else, it indicates that 
there is no VME device at the address 0x72000000. 


Themis Computer provides the sample program vme_rcw to illustrate the ways 
of accessing VMEbus addresses by using the vmeXXdYY file 





44.2 Using mmap 


A faster way to access VMEbus space is to use the mmap(2) system call. 
mmap() establishes a mapping between the user process's address space and a 
memory object represented by an open file. The /dev/vmeXXdYY files can be 
used for mmap() as well. e.g. To access a region of length 1000 bytes in the 
VMEbus space, starting from location 0x300, the following code segment can 
be used: 


int vme; 
caddr_t pageptr; 


i£ ((vme = open("/dev/vme32d32*,O_RDWR)) < 0) ( 
perror(*open error on VME file‘); 
return; 
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if ((pageptr = mmap((caddr_t)0L, roundup( 1000, PAGESIZE), 
PROT_READ|PROT_WRITE, MAP_SHARED, vme, 
(off_t) (0x500 & PAGEMASK })) (cadde_t)-1) { 
perror(*mmap error"); 
return; 





Note that the ‘off’ parameter to mmap() is constrained to be aligned at a page 
boundary. The ‘len’ parameter does not have a size or alignment constraint. 
The success of mmap() does not imply that the specified range of VMEbus is 
valid and accessible. If the region specified by [ off, offlen ] is not a valid 
VMEbus address region, access to the region will result in a SIGBUS signal. It 
is often convenient to catch this signal and take some action. The following 
code snippet sets up a catching mechanism for SIGBUS and SIGSEGV: 











void busError(int sig_num ) 


t 
print£("\nBus Error: received signal :#d\n*, sig_aum); 


return (0); 
) 


main(} 


signal(SIGBUS, busError) ; 
signal (SIGSEGV, busError); 
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Themis Computer provides a sample program named ‘vme_mmap’. This 
program is a good example of using mmap() to handle regions of varying 
sizes. The program also handles bus errors generated by access to an invalid 
region. 'vme_mmap’ can also be used to test a VMEbus board in a tumber of 
ways. 


4.4.3 DMAon the VMEbus 
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Direct Memory Access is the process by which a device takes control of the bus 
and performs data transfers to (and from) main memory or other devices. The 
device does this work without the help of the CPU, DMA transfers occur at 
significantly higher speeds as compared to normal transfers using 
read()/write() or mmap() 


On Themis SPRAC 10MP platforms, DMA access to the VMEbus is provided 
by the Newbridge SCV64 VMEbus Controller. The vmedma driver provides 
user access to the DMA features of the SCV64 controller. Using the ioct! 
interface provided by the driver, the user program can utilise the DMA engine 
and achieve high rates of data transfer. 


Typically a DMA transfer occurs between memory and the VMEbus. The 
memory location is specified by a user virtual address that is usually obtained 
via malloc() or mmap(). The VMEbus location is specified by a physical 
VMEbus address. The VMEbus address space does not have to be mapped into 
user memory. 


In addition to transfers between VMEbus and memory, the vmedma driver 
also supports transfers from memory to memory and VMEbus to VMEbus. 
Depending on the capabilities of the hardware platform, these transfers may be 
emulated in software. 


The ioctl interface to the vmedma driver enables user programs to control the 
DMA transfer in a variety of ways. These include 


1, Specify the VME address space for source and destination (16-bit, 24-bit, 32- 
bit or 64-bit) 


2. Specify the size of data transfer (16-bit, 32-bit, or 64-bit). 
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3. Specify whether Block Transfer mode will be used (Block Transfer mode is a 
feature of VMEbus in which the address information is placed only once at 
the beginning of the data transfer. Subsequent data transfers in the same 
block cycle automatically increment the addresses.) - 


4. Specify that the user buffers be locked into memory and any setup work 
done in the kernel be retained. The buffers are later released by the 
VIOCRELBUF ioctl command. This feature greatly increases the efficiency of 
repeated DMA transfers. 


5. Specify that the user program not block awaiting the completion of the 
DMA transfer. Completion of the transfer is indicated to the user process by 
the generation of a SIGIO signal. 


6, Interrogate the capabilities of the underlying hardware mechanism. e.g. on 
SpARC 10MP, memory to memory DMA transfers cannot be performed in 
hardware. The driver will emulate such a transfer in software. The 
VIOCGETCAP ioctl command provides the user program to determine 
details such as these. 


The following code segment illustrates a simple DMA transfer from memory to 
VMEbus address 0x72a00000: 


tinclude <themis/vmedmaio.h> 


struct vme_dmacopy dma;/* DMA request structure */ 
int i; 
int fd; 
long int * to_buf; /* memory buffer */ 


/* loop counter */ 
/* VME DMA engine fd */ 


open the DMA engine */ 
((£d = open(*/dev/vmedma0", O_RDWR)) < 0) 


(void) 


fprinté(stderr,"%s: can't open /dev/vmedmad: %3\n", 


argv(0],sys_errlist{ermno]): 
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exit (1); 


/* allocate source memory buffer */ 
if ((to_buf = (long int *)malloc ( 1024 * sizeof(long))) == NULL) 
C 
fprintf(stderr, “%s: can't allocate source memory buffer: %s\n", 
argv(0], sys_errlist(errnol): 
exit (1); 
, 


/* initialise the memory buffer with numbers from 0 to 1023 */ 


for ( £ = 0; i < 1024; ite) 
to_buf[i] = i; 


/* set up the DMA request 


* - memory to VMEbus 
* - 32-bit data, 32-bit address 
fe - no BLT 


do not retain buffers 
7 


dma.dma_source = to_buf; /* DMA transfer is from memory to VMEbus */ 
dma.dma_dest = (void *)0x72a00000; 

dma.dma_sourcehi = dma.dma_desthi = 0; /* no 64-bit addresses */ 
dma.dma_count = 1024 * sizeof(long); /* length of data transfer */ 
dma.dma_result = NULL; /* we don‘t bother about the result area */ 


dma.dma_flags = VF_DVME; /* destination is VME; no other special stuff */ 
if ( doctl(£d, VIOCDMACOPY, &dma) < 0) ( 
fprintf(stderr, “$s: can't do DMA transfer: %s\n" 
argv(0], sys_errlist(errnol); 


free ( to_buf}; 
exit (1): 


free ( to_buf}; 


Rev, Dato: 3/19/96 Writing Programs for the VMEbus 41 





For VMEbus address spaces other than A32D32, the dma_flags needs to be 
properly set. .e.g for a DMA transfer from an A24D16 space toan A32D64 
space, the flags are: 


\VE_SVME24 | VE_SVMED16 | VF_DVME | VF_DVMED64. 


Themis Computer provides sample test programs that illustrate the use of the 
vmedma driver 


444 Performing a Slave Mode Access to Another VME Board 


Memory on the SPARCIOMP board can be accessed from another board on the 
VMEbus chassis. This type of access is called slave mode access. Slave mode 
access under Solaris is tied to the concept of Direct Virtual Memory Access 
(DVMA). DYMA is a facility present on SPARC hardware that allows a device 
driver to specify virtual addresses rather than physical addresses for a DMA 
operation. The kernel maintains a map that specifies the correspondence 
between the DVMA address and the physical memory. 


In a typical operation, the master issues an address on the VMEbus; this 
address falls within the slave address range of another board on the chassis. 
The VME controller on the slave board then converts the VME address into a 
MBus virtual address. ( For details on the conversion mechanism, refer to 
Section 6.2.5 of the SPARCLOMP Technical Manual.) The VME controller then 
performs a DVMA operation on the MBus to access the physical memory 
location. The MBus virtual address generated by the VME slave access must be 
configured in the MVIC translation table. Themis Computer provides a driver 
that performs this configuration; the driver allocates a DVMA region and sets 
it up for VMEbus slave access at a particular VMEbus address. The master 
board simply uses this VMEbus address and generates a slave access operation 
on the VMEbus. The system that allocated the DVMA memory can also access 
the region by using special ioctl calls provided by the driver. Please refer to 
vmedvma(7) for more information on the driver. 
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The following code segment sets up a memory region of size 8192 bytes for 
DVMA access: 


#include <themis/vmedvma.h> : 


int £4; 
struct vme_dvmacopy dma_req: 


/* open the device */ 
if ((£d = open("/dev/vmedvma", O_RDWR))<0) 
¢ 
perror("can‘'t open /dev/vmedvma"); 
exit (1); 
» 


/* allocate a DVMA region */ 

dma_req.size = 8192; 

if (ioctl (fd, VDMALALLOCATE, &dma_req) != 0) 
{ 





perror(*In allocating DVMA"); 
close (fd); 
return(-1); 

) 


print£ ("Allocated a DVMA region id : $d, at virtual address : %x\n", 
@ma_req.id, dma_req. addr); 


The ‘virtual address’ output by this program can be used by other boards on 
the VMEbus chassis to gain access to this DVMA region. e.g. If a second board 
on the same chassis needs to access this region, one can execute this command: 


> od -x /dev/vme24d32 [slave_address) 
where (slave_address} is the virtual address output by the program 


‘The DVMA region can be accessed from the same system by invoking the 
ioctl() calls implemented by the vmedvma driver. The following code segment 
fills a DVMA region with zeros, starting from offset 0x500. 
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struct vme_dvmacopy dma_write; 
char * buffer; 


buffer = malloc( 4096); 


dma_write.id = 1; 
dma_write.addr= (caddr_t) buffer; 
dma_write.size= 4096; 
dma_write.offset= 204 





if (Joctl(£d, VDMALWRITE, &dma_write) != 0) 
( 
perror("In initialising DVMA region"); 
close(£d): 
return(-1); 


Themis Computer provides the sample program vme_dvma that sets up a 
DVMA region for slave access. This region can then be accessed from another 
system on the VMEbus chassis using the vmeXXdYY files; the user can modify 
the contents of the region from one system and verify that both the systems 
share the same view of the contents of the region. 


4.4.5 Advanced Features of the VMEbus Interface 


The SPARCIOMP product provides powerful advanced features like 
generating a SYSRESET on the VMEbus, configuring the interrupt mechanism 
etc. Themis Computer periodically issues Technical Notes that detail these 
interfaces and ways to access them. These Technical Notes have been put 
together in the document named “Advanced Configuration of SPARC 10MP* 
Please contact Themis Technical Support for issues not covered in that 
document. 


Writing Programs for the VMEbus Rov. Date: 3/19/96, 


Writing VME Device Drivers 5 








device driver is a kernel module responsible for managing low-level 

1/0 operations for a particular hardware device. Some device drivers 

manage ‘fake’ devices that exist only in software. A device driver 
‘contains all the device-specific code to communicate with a device. Like the 
system call interface protects application programs from the specifics of the 
platform, the device drivers protect the kernel from the specifics of the devices. 
A device driver also provides a standard 1/O interface to the rest of the 
system; ie.,a user program should be able to open a ‘device file’ and issue (in 
‘most cases a subset of) standard system calls to the file 


The VMEbus interface of Themis Computer's SPARC 10MP is transparently 
implemented under Solaris 1.x (SunOS 4.1.3) and Solaris 2.x. The software 
interface is fully compatible with generic Sundm VME architecture systems. 
Any VME device driver that confirms to the appropriate Solaris Device Driver 
Interface will run unmodified on Themis platforms 


This guide is intended to highlight the VMEbus specific features that influence 
the design of drivers for VMEbus devices. It tries to provide basic information, 
and when needed, refers to sources for more detailed information on specific 
concepts. A full introduction to the principles of writing device drivers is 
beyond the scope of this guide. For information on writing device drivers for 
Solaris 1.x systems, please consult the document “Writing Device Drivers”. The 
book “SunOS 5.3 Writing Device Drivers” has extensive information on writing 
device drivers for Solaris 2.x systems 
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Themis Computer has developed a number of sample device drivers that 
illustrate the concepts covered in this chapter. Please see Chapter 8, Sample 
Device Drivers, for more information on the sample device drivers. These 
drivers, along with user level programs that interface to them, are provided in 
source code format. 


The last section in the guide discusses the situations where developing a 
custom device driver may not be necessary. The section discusses mechanism 
by which most device operations can be performed from the user level. 





In its current version, this guide focuses on the software interface provided 
under Solaris 2.x. However except some sections, the concepts in this guide 
apply to Solaris 1.1.1 systems also. 


Solaris 2.x Device Hierarchy 


Solaris 2.x systems support architecture independence of devices by using a 
layered approach. Each node in the tree structure has a specific device 
function. Standard devices are associated with leaf nodes. The drivers for these 
devices are called leaf drivers. The intermediate nodes in the tree are 
associated with buses, like SBus, VMEbus etc. These nodes are called bus 
nexus nodes and the drivers associated with them are called bus nexus drivers, 
The bus nexus driver encapsulates all the architectural dependencies of a 
particular bus. The leaf driver only needs to know the kind of bus it is 
connected to. 
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‘On Themis SPARCIOMP systems, the device tree looks like this: 





root 




















THEMIS,vme| iommu 











vmedma| | vmemem’ sbus 











sbusmem| | espdma 

















In this diagram, root, iommu, vme and sbus are bus nexus drivers. The iommu 
encapsulates the features of the [/O Memory Management Unit found on 
sundm systems. The vme driver encapsulates all the details of the 
implementation of the VMEbus interface. e.g. the vmemem driver, which is a 
leaf driver, only needs to know that it is connected to the VMEbus. 


Solaris, like other UNIX systems, represents devices as special files in the file 
systems. These files are advertised by the device driver and are maintained by 
the drvconfig(IM) program. Usually the special files are created under the 

/ devices directory and represent the hardware layout of a particular machine. 
sysdef(1) and prtconf(1) can be used to view the internal device tree. Symbolic 
links are created from the /dev directory to the special files in the /devices 
directory. User programs normally use the files from the /dev directory. 
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5.2 Features of the VMEbus 


‘The VMEbus is an industry standard device interfacing bus that supports 
multiple address spaces. This means that a single VMEbus system can support 
devices that are 16-bit, 24-bit or 32-bit. There are many other features of the 
VMEbus which concern the system programmer. Another peripheral bus 
present in many SPARC platforms is the SBus. 


VMEbus has many features that influence the design of device drivers written 
to operate on the bus. Some of these features require the VME board to be 
configured in a particular way. Some of the features require configuration from 
the Open Boot PROM. And some of the features need to be included in 
hardware configuration files for the device driver. 


VMEbus address space is not different from the physical memory space. A 
‘VMEbus address is indistinguishable from a memory address. Each card on 
the VMEbus has its own address. Usually this address is configurable, The 
address remains the same irrespective of the slot that the card is plugged into. 
In contrast, the SBus is geographically addressed; the address of a card is 
determined by the slot it is plugged into. 


VMEbus supports multiple address spaces. A VMEbus system can support 
either 16,24 or 32 address bits and either 16 or 32 data bits. Some VMEbus 
cards can respond to multiple sizes of address bits. These cards must be 
configured for the desired access mode. Usually this configuration can be done 
by jumper settings. It is necessary for the device driver developer to specify the 
address space supported by the device in the hardware configuration file. 


VMEbus devices are not self-identifying i.e. they do not provide information 
themselves to the system. Drivers for VMEbus devices need to have a probe() 
entry so that the kernel can determine if the device is really present. Additional 
information about the device must be provided in a hardware configuration 
file. See driver.conf(4) and vme(4) for more information, 


VMEbus interrupts are vectored. When a device interrupts, it provides the 
priority as well as an interrupt vector. The kernel uses the information to 
uniquely identify the interrupt service routine to be called. The hardware 
configuration file must specify each priority-vector pair that the device may 
issue. 
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5.3 Configuration Files for VME Device Drivers 


Driver configuration files pass information about device drivers and their 
configuration to the system. Since VMEbus devices are not self-identifying, 
drivers for these devices need to use driver confi- guration files to inform the 
system that the device hardware may be present. The configuration file also 
must specify the device addresses on the VMEbus and any interrupt 
capabilities that the device may have. Please see driver.conf(4) and vme(4) for 
more details on the configuration files. 


The syntax of an entry in the configuration file is: 





name="driver name* class="vme" reg= 
interrupts=* 





Specifying class as “vme" indicates to the kernel that the device driver is for a 
VMEbus device and should be attached to the bus nexus driver for VMEbus. 
‘On SPARCIOMP systems, the bus nexus driver is named vme. 


‘Two common properties of interest to VME device drivers are the reg and 
interrupts properties. The reg property is an array of 3-tuples: address space, 
offset and length. Each 3-tuple describes a contiguous resource (registers) that 
can be mapped. The value of the address space is derived from the following 
table: 


Tate 51 Address Space 
































Address Space Value 
A16D16 Oxad 
‘A24016 Oxad 
A32016 Ox 
A16032 Oxéd 
A24D32 Ox7d 
32032 Oxdd 
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5.4 Probing devices 
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eg. For a device that supports A24D32 and has a set of registers that are 32- 
byte long and start at address Oxee00, the following 3-tuple can be used: Ox7d, 
Oxee00,32. Multiple register sets are separated by commas. 


VMEbus supports vectored interrupts. The interrupts property in the driver 
configuration file specifies all the interrupts that the device may generate. The 
interrupts property is an array of 2-tuples: VMEbus interrupt level, VMEbus 
vector number. e.g. for a device that generates interrupts at VME level 3 with a 
vector of 0x81, this two-tuple can be used: 2, 0x81. The VMEbus interrupt level 
has a value between 1 and 7, and the vector a value between 0 and 255. 


All VMEbus device drivers must provide reg properties. The first two integer 
elements of this property are used to construct the address part of the device 
name under /devices. Only devices that generate interrupts need to provide 
interrupts properties. 


It is to be noted that the DDI/DKI functions are capable of handling the 
VMEbus specific features, provided that the hardware configuration file is 
correct. e.g. if the hardware configuration file correctly defines a register set, 
the ddi_map_regs() function can be used to map the register set into kernel 
address space, without any extra effort from the driver code, 


Since VME devices are not self-identifying, drivers for these devices are 
required to have a probe entry point. Usually the probe entry point tries to. 
map the registers and then attempt to access the hardware using any of the 
peek and poke routines, The probe entry point should not initialize the device 
in anyway; it also should not initialise any of the software state. 


Mapping registers from VMEbus space does not need any special 
considerations. The ddi_map_regs() function call can be used to map the 
registers; this function will take care of the VMEbus address space that the 
register set is in. 


The following code segment is an example of mapping a register set and 
‘carefully’ accessing a byte in the set 
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* xxprobe - probe for this device 


a7] 


static int 


xxprobe(dev_info_t ‘dip) 


{ 
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struct my_reg_str ‘regs; /* Device registers */ 


caddr_t kaddr; /* mapped register address */ 
int retval; /* return value */ 

y* 

* If we're self-identifying, then we're here. 

v 


if (ddi_dev_is_sid(dip) == DDI_suCCESS) 
return DDI_PROBE_SUCCESS; 


” 

* Probe the device by mapping the registers, and reading the 

* command register and the parm? register...This assures that 

* something* is there. The attach routine will try to run 

* more rigorous checks. So this simple check is all we 

* really need here. 

a 

if ((retval = ddi_map_regsidip, 0, skaddr, 0, 0)) != DDI_SUCCESS) ( 
emn_err (CE_WARN, "xx¥d (probe): can't map my registers, errortd\n", 

ddi_get_instance(dip), retval); 

return DDI_PROBE_FAILURE; 








regs = (struct my_reg_str *)kaddr; 
retval = ddi_peekl(dip, (long *)&regs->command, (long *)0) 
== DDI_SUCCESS ? DDI_PROBE_SUCCESS : DDI_PROBE_FATLURE; 


if (retval == DDI_PROBE_succESS) 
retval = ddi_peeklidip, (long *)&regs->parm?, (long *)0) 
DOI_SUCCESS ? DDI_PROBE_SUCCESS : DDI_PROBE_FAILURE; 





ddi_unmap_regs{dip, 0, gkadér, 0, 0); 


retura retval; 
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5.5 Registering Interrupts 


552 


‘VMEbus interrupts are vectored. When a device interrupts, it provides the 
priority as well as an interrupt vector. The kernel uses the information to 
uniquely identify the interrupt service routine to be called, The hardware 
configuration file must specify each priority-vector pair that the device may 
issue. Once this has been done, the driver code can call the ddi_add_intr() 
function to egister the interrupts. On return from this function, the fourth 
arguemnt contains a pointer to useful information like theVMEbus interrupt 
priority and the VMEbus vector number. 


The following code segment provides an example of registering an interrupt 
with the keel; the code first gets the number of interrupt specification in the 


configuration file; then it registers an interrupt handler for each interrupt 


specification. 


static int 
xxattach{dev_info_t * dip, ddi_attach_cmd_t cmd) 
( 

struct xxstat * xsp 

int mbine,i; 


i£ ( ema {= DDI_ATTACK) 
return (DDI_FAILURE) ; 


/* get the number of interrupt definitions */ 
if (ddi_dev_nintrs(devi, gnbint) DDI_FAILURE) 
¢ 





cmn_err(CE_WARN, "xx: No interrupts property.*); 
geturn (DDI_FAILURE) ; 





i < mbint; i++) 





/* Register first with a null handler so that the interrupt 
* routine doesn't grab the mutex 
2h 





4€ ( ddi_add_intr(dip, iblock_cookie[i] NULL, 





axsp~ 
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( (lint (+) (caddr_t} nulldev, NULL} DoI_success) 


cmn_err(CE_WARN, "xx: cannot register interrupt."); 
return (DDI_FAILURE); 


/* Initialise the mutex now. */ 
mutex_init ( &xsp->mu, "xx mutex", MUTEX_DRIVER, 
(void *) xsp->iblock_cookielil); 


/* Remove the interrupt and register again with the correct 
* interrupt handler. 
37 





ddi_remove_intr ( dip, i, xsp->iblock_cookie(il}; 





til, 
DDI_sUCCESS) 


( ddi_add_iner(dip, i, &xsp->iblock_coo 
&xsp->idevice_cookiefi], xxintr, NULL) 








emn_err(CE_WARN, “xx: cannot register interrupt 
return (DDI_FAILURE); 


(CE_NOTE, "Registered interrupt td with priority %d and 
vector Oxtx", 

i, xsp->idevice_cookie(i] .idev_priority, 
xsp->idevice_cookie(i] .idev_vector) ; 


‘Themis Computer provides a sample device driver, vmeintr, to illustrate the 
use of interrupts in device drivers. This driver is provided along with the 
Source code and a sample configuration file. The reader may wish to study the 
source code for this driver to gain a better understanding of handling 
interrupts in device drivers. 
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5.6 Allocating DVMA Space 


Direct Virtual Memory Access is a facility present on SPARC hardware that 
allows a device to specify virtual addresses rather than physical addresses for 
a DMA operation, 


‘The kernel maintains a map that specifies the correspondence between the 
DVMA address and the physical memory. It is the responsibility of the device 
driver to set up the memory region for DVMA access. 


Setting up a DVMA region is a two-step process: allocating memory and 
allocating DMA resources for this memory region. The following code segment 
is an example of setting up a DVMA region of size ‘len’ bytes. 


While allocating memory and setting it up for DVMA, the driver can describe 
the capabilities of the DMA engine to the kemel by using a ddi_dma_lim_t 
structure. On SPARCIOMP systems, the capabilities are as follows: 


static ddi_dmalimt limits = 


¢ 
0x0, 

Oxgffeeeee, 
OxfEteftfe, 





caddr_t kmem_base 


int reqid, real_len, req_len; 


ddi_dma_handle_t handle; 
ddi_dma_cookie_t cookie; 
dma_req_t ‘reap; 


req.len = len; 
real_len = 0; 


y* allocate memory */ 
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if (ddi_mem_alloc (xsp->dip, glimits, 
(size_tireqilen, 0, &kmem_base, 
(uint *) &real_len) DDI_SUCCESS) 








cmn_err (CE_NOTE, ‘ddi_mem_alloc failed.* 
return (ENOMEM) ; 
) 


/* set it up for DMA access */ 
if (ddi_dma_addr_secup (xsp->dip, (struct as *) NULL, 
kmem_base, reat_len, 
DDI_DMA_RDWR, DDI_DMA_DONTWAIT, 0, &limits, 
&handle) != DDI_DMA_MAPPED) 





ddi_mem_free (kmembase); 
cmn_err (CE_NOTZ, “ddi_dma_addr_setup failed. 
return (EFAULT); 





) 


/* extract the virtual address of the memory region. 
* this can be obtained from the DMA cookie structure. 
4 


if (ddi_dma_ntoc (handle, 0, &cookie) != DDI_SUCCESS 


i 
ddi_dma_sync (handle, 0, real_len, DDI_DMA_SYNC_FORDEV) 


!= DDI_SUCCESS) 


ddi_dma_free (handle); 
ddi_mem_€ree (kmem_base) ; 

emn_err (CE_NOTE, * ddi_dma_sync() failed\n*); 
return (EFAULT); 


cmn_err ( CE_NOTE,"Virtual address of memory is Oxtx*,kmem_base) ; 
cmn_err ( CE_NOTE,"Virtual address of the DVMA region is Ox%x", 
(caddr_t} ccokie.dmac_address ); 
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The address contained in the ‘DMA cookie’ is the ‘virtual address’ of the 
DVMA memory region and can be used to access the memory region over the 
VMEbus. e.g. if the ‘virtual address’ printed by the second cmn_err statement 
is 0x388, you can access this memory region from another system on the 
VMEbus chassis by using this command: 


Hod -x /dev/vme24d32 0x588 


Themis Computer provides a sample device driver, vmedvma, to illustrate the 
use of DVMA in VME device drivers. This driver is provided along with the 
source code and a sample configuration file. The reader may wish to study the 
source code for this driver to gain a better understanding of using DVMA from 
device drivers. 
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if 


‘ 


(ddi_map_regs (dip, 0, &map_space, 0x66000000, (off_t) 8192) != 


‘On some occasions, it would be convenient to map a chunk of VMEbus 
address space into the system's memory. From the user level, this can be done 
by doing a mmap() operation on the appropriate /dev/vmeXXdYY file, From 
the driver level, mapping VMEbus address space can be done by using the 
ddi_map_regs() function. e.g. to map two pages of VMEbus space starting at 
location 0x66600000, the following code segment can be used: 








DDI_SUCCESS) 


return (EFAULT); 


On return from the function, map_space contains the base address of the 
kernel virtual region. 


‘There are many caveats to using ddi_map_regs() to map a portion of VMEbus 
address space. 


1. An A32D32 device can only map a chunk from A32D32 address space. 
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2. The address space indicated by [offset, offset +len] must be a valid region on 
the VMEbus. 


3. Access to the mapped region should be localized. Subsequent access to 
locations that are far apart will result in many page faults, particularly on 
regions of larger sizes 


It is prudent to use the ddi_peek() and ddi_poke() routines to access a region 
mapped using ddi_map_regs() 


5.8 Driving Devices Without Writing Device Drivers 
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As mentioned before, device drivers protect the rest of the kernel from the 
specifics of hardware devices. Most hardware devices would necessiate the 
development of a device driver before they can be used on a computer system. 
However the features of the VMEbus and the design and implementation of 
the Themis Computer software interface for VME alleviate the need for 
specialised device drivers for most simple VME devices. This provides a 
tremendous advantage to programmers writing applications for these simple 
devices, 


In Solaris 2.x device drivers are dynamically loadable. This avoids the need to 
relink the kernel and reboot the system whenever a driver is modified. 
However, a fault in the driver could stil cause the kernel to panic, resulting in 
long downtimes for the machine. Further, an abnormal shutdown of the 
machine, as in the case of kernel panic, could cause the disk to be corrupted 
and some important files to be lost. These problems cna be avoided if the 
program driving the device executes in user mode instead of kernel mode. 


This section discusses some ways by which an user program can do device 
operations that are traditionally performed by a device driver. The section is 
intended to clue the programmer on to the possibilities of accessing devices 
from user level. The reader is encouraged to go through the source code of the 
sample drivers to gain an insight into how they can be used for user-level 
access. 





In simplistic terms, a device can be viewed as a collection of registers that are 
addressable. Almost all of these registers can be either read from or written to 
Some of them allow both read and write access. Access to many of the registers 
results in effects like resetting the value of the register, clearing the interrupt 
etc. Some registers require a particular sequence of accessing them. Some 
registers have specific data widths that can be used to access them. Though 
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there are some devices that have some very peculiar behavior, most devices 
can be modeled as a collection of registers. Such devices, if they are VMEbus 
devices, can be programmed and used without the need for a specialised 
device driver. - 


As mentioned before, VMEbus addresses are not distinguishable from memory 
addresses. The vmemem drivers from Themis Computer, which is the device 
driver for the /dev /vmexxdyy files, enables an user program to access any 
address in the VMEbus space. 


This feature can be used to access the registers of a device from a user 
program. The user program needs to open the appropriate /dev/vmeXXdYY 
file, Iseek to the address of the device registers and do a read or write 
operation. The vmemem driver performs the read/write opeartion ‘carefully’ 
by using the ddi_peek() and ddi_poke() calls. If the user program opens the 
appropriate file and the read/write access meets the alignment criteria of the 
device, the device registers can be easily programmed from the user program. 


e.g To access a device that supports 32 address bits and has 32-bit data, with 
the registers starting at offset 0x7e000000, the user program needs to open 
/dev /vme32d32 and Iseek to offset 0x7e000000. Please note that the registers 
Of this device could be 8-bit wide, 16-bit wide or 32-bit wide. If the read/write 
call is issued with the appropriate length, the vmemem driver will issue the 
appropriate ddi_peek or ddi_poke call. 


Note that the mmap() interface of the vmemem driver does not use the 
ddi_peek /ddi_poke calls. in such cases, acces to all non-existent address space 
will cause a SIGBUS signal to be sent to the user program, 


The vme DVMA driver provided by Themis can be used to support more 
powerful devices that are capable of performing DMA operations on the 
VMEbus. e.g. To program a device to perform a DMA operation to on-board 
memory space, the user program can do the following: 


1. Open the relevant /dev/vmeXXdyy file and Iseek to the beginning of the 
register space. 


2. Open /dev/vmedvma and allocate a DVMA region. 


3. Use the virtual address returned by the allocate ioct! to program the DMA 
engine on the device. 


4. Use the other ioctls provided by the vmedvma driver to access the DVMA 
region 
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Devices that issue interrupts pose more of a problem when accessed from the 
user level. In some cases the devices can be programmed to not raise 
interrupts. Input/output in such cases may be done by making the user 
program ‘busy-wait’. In other cases, the vmeintr driver can be used fo receive 
the interrupt and signal a user program when the interrupt is raised. The user 
program can then look at the device registers and take appropriate actions, 


Future releases from Themis Computer will include a “user level driver” that 
can be used to program a simple device. 
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This guide is intended to provide helpful information and tips to systems programmers 
who use the Themis SPARC 10MP boards. The next section is intended to address the 
programmers who wish to program the Themis SPARC 10MP board for the VMEBus 
without the aid of an operating system or real-time kemel. Further sections are 
intended to address the programmers who wish to access the Themis SPARC [OMP 
board from any of the supported Operating System environments. 


Detailed information concerning on-board device interfaces, memory maps and device 
accesses are contained in the appendices and should be consulted while reading this 
guide. 


‘The Themis SPARC 10MP processor board implements a Sun SPARCstation10 
compatible workstation on a single- or double-width 6L VMEbus board. A full VME 
master/slave interface is included, using the Fujitsu MBus to VMEbus Interface 
Controller. 


This guide is primarily concemed with the implementation and programming of 10MP 
that are not common to the superSPARC family of workstations (SPARCstation 10). 
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6.2 Overview of VME Interface Under Solaris 1.1.1B/2.X 
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Great effort has been expended to achieve complete compatibility between Sun VME 
implementations and the device driver interface implemented for the 1OMB board 
under Solaris, 


This section is primarly concerned with the implementation and programming of 1OMP 
specific features that are not common to the microSPARC II family of workstations 
(SPARCstation 5). It assumes that the reader is familiar with the sun4m architecture 
and the concepts of VMEbus and device drivers. A separate tutorial provides more 
detailed information for readers who are not familiar with these concepts. 





‘The VMEbus interface of the 1OMP is transparently implemented under Solaris 1.X 
(SunOS 4.1.3) and Solaris 2.X. The software interface is fully compatible with generic 
Sun4m VME architecture systems. Any VME device driver that confirms to the 
appropriate Solaris Device Driver Interface will run unmodified on Themis platforms. 


‘Themis Computer has developed a number of device drivers to provide the necessary 
software interface needed by system programmers, The drivers can be classified into 
three categories: 


© VMEbus Nexus drivers 
© Utility drivers 
* Sample drivers 


‘The drivers are described in the following subsections. Themis also provides online 
anual pages for all the drivers included in the software interface. These manual pages 
include more detailed information on the drivers. 
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6.2.1 VMEbus Nexus Driver 
‘The tvme driver forms the core of the software interface provided by Themis 
Computer. tvme is a bus nexus driver that encapsulates all the architectural features of 
supporting the Themis 10MP board on Solaris systems. This driver is configured to be 
permanently loaded as the bus nexus driver for the VMEbus. 
| vmedma| | vmemem| sbus 
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sbusmem| | espdma 


Any driver that specifies its class or parent as vme will be attached to the vme driver. 
‘The vme driver provides support for all VMEbus operations, including VME interrupt 
processing, Direct Virtual Memory Access (DVMA) on the VMEbus, mapping of 
registers on the VMEbus to kernel space, mapping of VMEbus memory to user address 
space through mmap(). etc. 
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‘The tvme nexus driver also exports certain capabilities that can be used by VMEbus 
leaf drivers, This enables leaf drivers to perform operations like Direct Memory 
Access in a very efficient manner. 





‘The tvme driver recongnizes the standard configuration file for VME device drivers. 
(see vme(4) ). The configuration of any vme device driver specifies the VMEBus 
interrupt level and the interrupt vector. The mapping of the VMEbus interrupt level to 
the SPARC interrupt priority level is as follows: 


Table 6-1 VMEbus Interrupt Mapping 





wees [11 [2 |8 [* [s |@ |? 
sparcio [1 [2 [a [5s |7 |e [1 fis 


























6.2.2 Utility Drivers 


‘These drivers are a standard part of the software interface provided by Themis 
Computer. These drivers provide a useful interface to system programmers who wish 
to utilize the different features of the VMEbus architecture. 


‘The vmemem device driver provides the standard /dev devices for accessing the 
VMEbus from user processes: 


Table 6-2 VME Device Drivers 






































Device File | Address Sizo | Data Transfer Size 
Idevimes2a32 | 32 32 
idevivmeszai6 | 32 16 
Idevivma2sas2 | 24 32 
idevivmezsdté | 24 16 
Idevivmeteds2 | 16 32 
Idevivmetéaté | 16 16 
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Readi), write() and mmapt) calls are supported and no special ioctl() calls are required 
to configure the interface. VME interface configuration is performed under OBP and 
should not be modified while the operating system is running 





On Themis SPRAC 10MP platforms, DMA access to the VMEbus is provided 
by the Fujitsu MVIC. The vmedma driver provides user access to the DMA 
features of the MVIC. Using the ioctl interface provided by the driver, the user 
program can utilise the DMA engine and achieve high rates of data transfer. 


6.2.3 Sample Drivers 


‘The software interface provided for the 1OMP platform fully suppons standard 
VMEbus device drivers written for Solaris environments. It is the intention of Themis 
Computer to fully support users who wish to write their own VME device drivers that 
would function on Themis SPARC 1OMP platforms. To aid these users and to illustrate 
the specific features of the VMEbus architecture, Them provides a aumber of sample 
device drivers. Themis provides the complete source code and the necessary 
configuration files for these drivers. 


« vmeintr: is a sample driver provided by Themis Computer to illustrate the 
vectored interrupt mechanism of the VMEbus. The vmeintr driver relies on the 
driver configuration files to specify the interrupts it should handle. Each instance 
of the driver registers the interrupts with the system. Through the ioctls 
implemented by the driver, the user can generate interrupts and send them to the 
appropriate driver instances. The interrupt generator and the interrupt receiver 
need to run on different computers. 








+ vmedyma: is a sample driver provided by Themis Computer to illustrate the use 
of Direct Virtual Memory Access within a device driver. The user can ask the 
driver to allocate a DMA region on the VMEbus. The driver allocates all the 
necessary resources to support a DVMA transfer to this region, The driver also 
implements mechanisms by which the user program can writer to or read from the 
DYMA region. 





+ simpledma: is a sample driver provided by Themis Computer to illustrate the use 
of Direct Memory Access within a device driver. It is a simplified version of the 
standard vmedma driver. This driver is mainly intended for programmers writing 
device drivers that perform DMA operations on the VMEbus. 
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generating a SYSRESET on the VMEbus, configuring the interrupt 

mechanism etc. Themis Computer periodically issues Technical Notes 
that detail these interfaces and ways to access them. These Technical Notes 
have been put together in this document. Please contact Themis Computer 
Technical Support for advanced configuration topics not covered in this 
document. 


Some of the sections in this chapter may apply to other Themis Computer 
products too, These are noted as applicable. 


T he SPARC 10MP product provides powerful advanced features like 
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7.1 Disabling VMEbus Interrupts 





TECHNICAL NOTE No 107-01 








‘SUBJECT: Disable VME interrupts on THEMIS boards 
BOARD: All 
‘O.S.: all (excopt solaris 1.x on the LXE) (*) 











Hardware rev: all 
DATE: April 20, 1995 














Problem: By default, VME interrupts are enabled on THEMIS boards. This can 
cause conflicts on the VMEbus, in multi CPU configuration, as there may be 
‘more than one interrupt handler for one particular VME interrupt level. 


Boards: all 
Operating systemiall Solaris, except 1.1 for LXE. 


Programming of VME interrupt mask is done under OBP, using nvramre 
commands 


THEMIS LXE: 





ok nvedit 

1: xx 5ffe.0014 20 spacec! 
BAC 

ok nystore 

ok setenv use-nvramrc? true 
ok reset 


VME BUS interrupt mask register 0x5ffe0014 is as follows: 
bit [7.1] : Vme IRQ 1.7. If set IRQ is enabled. 
-bit 0 : Arbitration mode. 0 = Single level, 1 = Round robin 


So, if xx is Oxfe (default), all interrupts are enabled, and VMEbus arbiter 
operates on single level (Bus level 3). 
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THEMIS LXE+ and 5-64: 





ok nvedit 

1: xx 7d00.00b0 20 spacel! 
24C 

ok nystore 

ok setenv use-nvramrc? true 
ok reset 


VME BUS interrupt mask register description is as follows: 
~ bit 6:VME IRQ7 





= bit O:VME IRQI 


(*) On the LXE running solaris 1.x, you need to disable interrupts from UNIX, 
alter the system is booted. Please contact Technical support for details. 
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7.2 Isolating Boards from VMEbus SYSRESET 





TECHNICAL NOTE No 120-00 7 








‘SUBJECT: Isolate board from VME SYSRESET. 





BOARD: THEMIS LXEplus,5-64, 10MP- 








0.8. all 





| Harewaro rov: at 
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ATE: May 9, 1995 








It can be useful to isolate a VME board from the VME sysreset signal, 
especially if you are running Solaris. 


To isolate the Themis 5-64, or the LXEplus from the VME sysreset, you have to 
remove a CMS resistor (R5300). After removing that resistor which is in fact a 
short (0 Ohms), the board will be disconnected from the VME sysreset signal, 
In case you want to connect the board to the sysreset signal again, use a solder 
bead to short R5500. 


NBiThe location of R5500 is different on the 5-64 and the LXEplus. Please see 
drawings enclosed. 


To isolate the 10MP from SYSRESET, you need to change the socketed PAL 
U2309 with a special PAL. Please contact Technical support to get that PAL. 
Note that after that modification, the 10MP won't receive SYSRESET from 
other boards, but will still be able to send it on the bus. 


Advanced Configuration of WMAP Rev. Date: 3/20/96 





7.3 Handling Data Mismatch Over the VMEbus 
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TECHNICAL NOTE No 133-00 > 








‘SUBJECT: Data mismatch over the VME. 





BOARD: THEMIS 10MP 





0.S.: Solaris 2.4 





Haraware rev: ail 








DATE: July 1, 1995 








There is a bug in solaris 2.4, in the way the MicroSparcll MMU is handled. This 
bug can result in data mismatch over the VME. Typically, you won't read back 
the same value that you write to a given VME memory range, especially if you 
make transfers of more that one MMU page (4k). 


The solution is to apply the Sun 101945 kernel jumbo patch. This is quite a big 
patch(16MB), and Themis is shipping it along with the 1OMP VME nexus 
driver. 





To apply it, you simply need to run the ./installpatch command at the patch 
directory level: 


# cd 101945-27 
#./installpatch . 


To check if you already installed that patch, you need to run the following 
command 


# showrey -p 


This will tell you what patches were already installed on your system, 
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7.4 Handling VMEbus Lock-Up Problems 





TECHNICAL NOTE No 137-00 








‘SUBJECT: VME lock-up problem on the 10MP_ 
BOARD: All 

0.8: all 

Hardware rev: all with C4 KSIC (and before) 
DATE: October 18, 1995 

STATUS: 


























There is a potential problem on the 10MP that after heavy SBUS and VME 
traffic, the board can no longer access VME. 


The problem is that the VMMU, in charge of translating SBUS addresses to 
VME addresses, is disabled at random times. Thus no further VME access is 
possible, and the CPU gets a bus error that will crash the system if the access is 
made by kernel code (device driver). 


The solution is to use the C5 KSIC (and above versions), This KSIC is actually 
disabling accesses to the VMMU registers, preventing the VMMU to get 
disabled. 


Note: How to check the version of your KSIC: 


->Please check the revision number that is written onto the KSIC iteself 
(Right in the middle of the 2 SBUS connectors). 


772 Advanced Configuration of (MP Rev. Date: 3/20/96 





7.5 Configuring VMEbus Release Mode 
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TECHNICAL NOTE No 122-00 - 








‘SUBJECT: VME release mode. ROR vs RWO 





BOARD: THEMIS LXEpius,10MP- 





OS. all 





Hardware rev: all 











DATE: Oct 19, 1995 





When a MASTER VME board wants to make a VME BUS cycle it has to request 
theVMEBUS from the bus controller (SYSCON). Then when the cycle is done, it 
will release the VMEbus, so that other MASTERS on the VME can request and 
be granted the VMEBUS. 


There are 2 modes of releasing the VMEbus: 
-ROR: Release on request. 
-RWD: Release when done. 


-In ROR mode the MASTER VME board will keep ownership of the VMEBUS 
(ie-keep BBSY asserted), until another MASTER request the VMEBUS. But one 
should be aware that this could result in VMEBUS starvation for every board 
located to the left of any ROR master. This is due to the fact that the SYSCON 
is granting ownership of the VMEBUS using the BUS GRANT daisy chain 
signals. Those signals are propagated from left to right of the chassis, starting 
from the SYSCON to the next VME board (board #1). If that next board is 
requesting the VMEBUS then it will consider it has been granted the VMEBUS 
by the SYSCON, 


Otherwise, it will pass the BUS GRANT daisy chain signal to the next board on 
its right(board #2) 


Now if board #1 is programmed in ROR mode, 


-In RWD mode, the MASTER VME board releases the VMEBUS as soon as the 
VME cycle it just performed is done. 
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How to program your board to switch to coupled mode: 


Themis 10MP and LXEplus: 





The default mode is RWD. Here is how to set the board in ROR mode. 


You have to use OBP avedit feature to add a FORTH command, that will be 
ran each time the board is booted. 


ok avedit 

1: 7400.0090 20 spacel@ df and 700.0090 20 spacel! 
2A 

ok nystore 

ok setenv use-nvramrc? true 

ok reset 
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4. Edit /etc/hosts and add an entry for the client: 


Sun Host Database 


T€ the NIS is running, this file is only consulted when booting 


127.0.0.1 localhost, 

* 

198.211.242.189 mpl12 loghost 
198.211.242.188 564_1 


“/etc/hosts" 9 lines, 167 characters 


5, Same thing under /etc/ethers {tftpboot) 


0:80:bé: 





564_1 





tc/ethers* (New file] 1 line, 20 characters 


6. Run add_client: 


mp112¥ /usr/etc/install/add_client -i 
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CLIENT FORM (?shelp] [DEL=erase one char] [RET=end of 
input data] 





Architecture Type : x{sundm.sunos.4.1.4] 


Client name + 5641 
Choice x{create] [delete] (display) [edit] 
Root fs : /export/root (sda) 144616448 Hog : sd0h 0 
Swap fs : /export/swap (sd0a) 144616448 Hog : sd0h 0 
Client Information : 

Internet Address + 198.211.242.188 

Ethernet Address : 0:80:b6:1:2:3 

NIS Type + x{none] [client] 

Swap size (e.g. 88, 8K, 8M) : 16M 

Path to Root + /export/root/S64_1 

Path to Swap + /export/swap/564_1 

Path to Executables Juse 


Path to Kernel Executables +: /export/exec/kvm/sundm.sunos.4.1.4 
Path to Home /home /mp112 
Terminal type sun 





Ok to use these values [y/n] ? 
Ux/Xzselect choice] [space=next choice] [7B/*! 
[*F/*N= forward] 





=backward] 
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7.6 Installing Solaris 1.x Patches on Diskless Clients 


Rev. Date: 3/20/96 





TECHNICAL NOTE No 145-00 : 








‘SUBJECT: Homogeneous server: Client install problem. 





BOARD: THEMIS LXEplus, 10MP 





0.S.: Solaris t 








Hardware rev: all 





DATE: Nov, 1995 








Themis VME boards are sometimes configured as a client diskless node. They 
use tftpboot, to boot from a Sun server machine, Then they mount their /root, 
/swap, /ust and /home file systems from a remote disk, using NFS. That kind 
of configuration can sometimes cause a problem, when installing the VME 
patch, that will permit the Themis board to access the VME bus: 


Under Solaris 1, VME software is provided under the form of modified Kernel 
binaries, not true device drivers like under solaris 2.4. So, applying the VME 
patch on the NES mounted partitions of the client, may sometimes result in 
patching some important kernel binaries on the server itself. 


‘The VME patch is only updating files located in the /usr/kvm directory, also 
known as the “kernel binaries” So, it is of the utmost importance to configure 
the client with a separate /usr/kvm directory than that of the server. In the 
case, where the diskless and the server are running 2 different versions of 
Solaris 1 (let's say solaris 1.1.2 and Solaris 1.1.1B), there is no problem, as in 
this case, running “add_services” will generate a /ust/kvm (kernel binaries) 
unique to the the client diskless. This directory will actually be located in: 
Jexport /exec/sundm.sunos.4.1.4. 





But in the case where the client and the server are running the exact same 
version of the Solaris 1 Operating system, "add_services” won't let you install a 
separate /ust/kvm for the client. Themis is currently in contact with SunSoft, 
to find a solution to that problem. 


In the meantime, there is a workaround to install, let's say a Solaris 1.1.2 
diskless client on a Solaris 1.1.2 server machine, 


(in the example below, mp1 12 is the server, and 564_1 is the client.) 
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1. During the Sysgen of the server, 


don’t forget to 


configure that machine as a server (versus a stand alone 


system). 


2. Under /export/exec/kvm/ directory, 


remove the 


sundm.sunos.4.1.4 directory (actually a link to 


/use/kvm) . 


3. Copy /usr/kvm in /export/exec/kvm/sun4m. sunos.4.1.4. 


cd /usr/kvm 
tar cvf /tmp/kvm 
ed /export/exec/kvm 
mkdir sundm.sunos. 





ery 


tar xvf /tmp/kvm 
1s 


Libkvm_p. 
né6sk 
machine 
mc68010 
mc68020 
mdec 
modload 
getcons ms 
i386 mpstat 
LAPK286 pdpli 
Libkvm.a ps 
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cd /export/exec/kvm/sundm.sunos.4.1.4 


Libkvmn.so.0.3pstat 


showrev 
sparc 
stand 
sun 
sun2 
sun3 
sun386 
sun3x 
sund 
sundc 
sundm 


sys 
trace 

u370 

ub 

u3b15 

u3b2 

u3b5 
unixname2bootaame 
vax 

w 
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Creating client '564_1° 


Updating the server's databases 

Setting up server file system to support client 

Making client's swap file 

Setting up client's file system 

Copying /export/exec/proto.roct.sunos.4.1.4 to /export/rcot /564_1 
Copying binaries 





Updating client's databases 
Setting up Client's ttytab 


7. On the server: Declare /export/exec/kvm/sundm.sunos.4.1.4 
in /etc/exports: 
(check Line #6) 





fuse 

home 

/var/spool/mail 

export /root /564_1 ~access=564_1, root=564_1 
export /swap/564_1 ~access=564_1, root=564_1 





export /exec/kvm/sundm.sunos.4.1.4 -rw=564_1,acces: 


564_1, root=564_1 





ec/exports* 6 lines, 184 characters 
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8. Update the client's /etc/fstab file: 


mp112: /export/root /564_1 / nfs rw 00 


mp112: /export/exec/sun4.sunos.4.1.4 usr nfs ro 0 0 
/usr/kvm nfs rw ro 0 0 


mp112: /export /exec/kvm/sun4m,sunos.4.1.4 
mp112: /home/mp112 Thome/mpl12 nfs xw 0 0 


mp112:/var/spool/mail /var/speol/mail nfs rw 0 0 
mp112:/export/share/sunos.4.1.4 /usr/share nfs rw 0 0 


“/etc/fstab" 6 lines, 298 characters 


9. Boot the client: 
ok boot net 
Resetting 





zs is initialized 
Initializing TLB 
Initializing Swift Cache 


Allocating SRMMU Context Table 
Setting SRMMU Context Register 
Setting SRMMU Context Table Pointer Register 
Allocating SRMMU Level 1 Table 


Level 1 Table allocated, Available Memory 0x03feec00 


Mapping RAM 
Mapping ROM 


ttya initialized 
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i 

SPARCstation 564, No Keyboard 

ROM Rev. 2.14.4, 64 MB memory installed, Serial #4096. 
Ethernet address 0:80:b6:1:2:3, Host ID: 89001000. 








Rebooting with command: net 

Boot device: /iommu/sbus/Ledma@4,8400010/1e@4,8c00000 File and args: 
Automatic network cable selection succeeded : Using TP Ethernet Interface 
14400 

Automatic network cable selection succeeded : Using TP Ethernet Interface 
Using IP Address 198.211.242.188 = C603F2BC 

hostname: 564_1 

domainname: noname 

server name 'mpl12* 

root pathname '/export/root/564_1' 

root on mpll2:/export/root/564_1 fstype nfs 

Boot: vmunix 

Size: 1548288+464288+225760 bytes 

VAC ENABLED 

SunOS Release 4.1.4 (GENERIC) #1: Fri Jun 16 17:00:30 PDT 1995 
Copyright (c) 1983-1993, Sun Microsystems, Inc. 

cpu = THEMIS, 564 

mod0 = FMI,MB86904 (mid = 0) 

mem = 65220K (0x3£b1000) 

avail mem = 61083648 

entering uniprocessor mode 

Ethernet address = 0:80:b6:1:2:3 

espdmad at SBus slot 4 0x8400000 

esp0 at SBus slot 4 0x9800000 pri 4 (onboard) 

esp0: Warning- no devices found for this SCSI bus 

SUNW,bpp0 at SBus slot 4 0xc800000 pri 3 (sbus level 2) 

iedmad at SBus slot 4 0x8400010 

e0 at SBus slot 4 0x8c00000 pri 6 (onboard) 

Warning: Out of range register specification in device node <flash> 
Warning: Out of range register specification in device node <flash> 
Warning: Out of range register specification in device node <flash> 
z80 at SBus slot 4 0x1100000 pri 12 (onboard) 

zsl at SBus slot 4 0x1000000 pri 12 (onboard) 

SUNW, fdtwoO at SBus slot 4 0x1400000 pri 11 (onboard) 
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SBVME: address 1080000 (vme32432) not found in VME range table; ignoring 


SBME: address 1080400 (vme32432) not found in VIE cange table; ignoring 
SBVME: address ‘1080800 (vme32432) not found in VME range table; ignoring 
SBVME: addcess 1080c00 (vme32d32) not found in VME range table; ignoring 
SBVME: address ‘1001000 (wne32432) not found in VME range table; ignoring 
SBVME: address 1000000 (vme}2d32) not found in WME range table; ignoring 
SBVME: address "Jo10000 (vme32432) not found in VME renge table; ignoring 
SBVME: address Jo20000 (vme32432) not found in WME range table; ignoring 
SBwME: address 1020000 (vme32432) not found in VME range table; ignoring 
SBVME: address 72000000 (vme32432) not found in VME range table: ignoring 
SBVME: address 2010000 (vme32432) not found in WE range table; ignoring 
SBVME: address 2020000 (vme32432) not found in VME range table; ignoring 
SBVME: address 77020000 (vme32492) not found in VME range table; ignoring 
hostname: soa 





domainname: noname 
root on mpli2:/export/root/564_1 fstype nfs 
swap on mpll2:/export/swap/564_1 fstype nfs size 16384K 
dump on mplL2:/export/swap/564_1 fstype nfs size 16372K 
checking filesystems 
Automatic reboot in progress... 
Wed Nov 15 15:14:05 PST 1995 
checking quotas: done. 
starting rpc port mapper. 
starting RPC key server. 
network interface configuration: 
le0: £lags=63<UP, BROADCAST, NOTRAILERS, RUNNING> 
inet 198.211.242.188 netmask ££f€££00 broadcast 198.211.242.0 
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ether 0:80:b6:1:2:3 
100: £lags=49<UP, LOOPBACK, RUNNING> inet 127.0.0.1 netmask ££000000 
rdate mpi12 

Wed Nov 15 15:14:15 1995 
mount -vat nfs 

mpl12:/export /exec/sun4,sunos.4.1.4 already mounted 
mpll2:/export /exec/kvm/suném.sunos.4.1.4 already mounted 
export/share/sunos.4.1.4 mounted on /usr/share 

home/mpl12 mounted on /home/mp112 

mpl12:/var/spool/mail mounted on /var/spool/mail 

starting additional services: biod. 

starting system logger 

starting local daemons: auditd sendmail statd lockd. 

link-editor directory cache 

preserving editor files 

clearing /tmp 

standard daemons: update cron uucp. 

starting network daemons: inetd printer. 

Wed Nov 15 15:14:19 PsT 1995 











$64.1 login: 
564_1 login: root 
Nov 15 15:14:50 564_1 login: ROOT LOGIN console 
Last login: Wed Nov 15 14:44:49 on console 

SunOS Release 4.1.4 (GENERIC) #1: Fri Jun 16 1 








00:30 Por 1995 





56414 
364_1% 
564_1¢ 
564_1¢ 
56418 df 
Filesystem kbytes used = avail capacity Mounted on 
mpi12: /export /root/564_1 

189383 59730110715 358 / 
mpii2:/export /exec/sun4.sunos. 4.1.4 

710110 162944 476155 25% suse 
mp112:/export /exec/kvm/sun4m.sunos.4.1.4 

199383 $9730 110715 35% fasr/kvm 
mp112:/export/share/sunos.4.1.4 

710110 162944 476155 25% /usr/share 
mp112:/home/mp112 710110 162944 476155 25% fhome/mp112 


mp112:/var/spool/mail 
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189383 © 59730110715 358 /var/spool/mail 
564_1# 


10. Download the VME patch on the client, and install them. 


11. Reboot the client. If it's a THEMIS 5-64, you need to run ‘add_vme" 
under OBP, to declare your A32 boards, that will be 
accessed by the 5_64. 
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TN102:VME configuration on SPARC 10MP 





Object: Configure VME interface 
Boards:SPARC 10MP 
Operating system:SOLARIS 2.3, 24 


1) Default values for VMEBus request level, size of A32 slave window, and 
base 


address of A32 slave window can be overriden by OBP properties. 

‘These properties are respectively named “bus-request-level”, "a32-size" and 
“a32-base”. They are replicates of the corresponding bit fields in the VME 
Master and Slave Configuration registers described at the end of this note. 


Generally spekaing, the command syntax for setting an OBP property is 





<hex value to set> xdrint " <property-name>" attribute 
Notice that the space character between the quote and the property name is 
mandatory. 


Such settings can be made permanent in NVRAM for automatic execution, by 
use of 


“nvedit". See manual “OpenBoot Command Reference’ for a description of 
avedit. 


Example : Set Bus request level to 2, A32 slave address to 0x80000000, A32 
slave 
window size to 32 MB. 


ok nvedit 

1: ed /THEMIS,vme 

2: 2 xdrint " bus-request-level” attribute 
3: 80 xdrint * a32-base” attribute 
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4:1 xdrint * a32-size” attribute 
5:4 

ok nvstore 

ok setenv use-nvramrc? true . 
ok reset 


(<Caution> : the last command will reset the board !) 
Changes may be examined by : 


ok cd /THEMIS,vme 
ok attributes 


Note that A32 slave access is normally left disabled. Use patch_kmem below to 
enable it. 


2) Other default system values for configuration of VME interface can be 
overridden by patching MVIC registers from applications running in user 
space. 


As a matter of fact, MVIC registers are accessible in /dev/kmem, starting at 
location 0xFFED.B000. 

This address corresponds to the “address” property, as defined by OBP in the 
"/THEMIS,vme" device node. 


included in this, 





A sample C file for patching /dev/kmem, “patch_kmem. 
note. It must be run in superuser mode 


patch_kmem ffedbif0 
+> Read VMEbus master configuration register 


patch_kmem ffedbfe8 2800000 
-> Set VME A3z2 slave address to 0x8000.0000, 
VME A32 slave window size to 64 MB. 


VMEbus Master Configuration Register (offset 0xFFO) 





bit [31]VME Slave A32 Address space enable 
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If set to 1, slave access in A32 address space is enabled. 


bit (30]VME Slave A24 Address space enable 
If set to 1, slave access in A24 address space is enabled. 


bit [29] VME Slave Al6 Address space enable 
If set to 1, slave access in A16 address space is enabled. 
Always to be left disabled under Solaris. 


bits [28:13]Reserved 


bits [14:11] A24 Slave Base Address 
‘These 4 bits determine where in the A24 slave address space 
the IMB DVMA region will respond to. Note that DVMA (Direct 
Virtual Memory Access) is reserved for SunOS device drivers. 


Bits [14:11] correspond to bits [23:20] of VME A24 address. 
bits (10:8] Reserved 


bits (7:6] VMEbus DTACK time-out 
This field determines how long the MVIC waits for a slave to 
respond with a DTACK before asserting a Bus Error on the 
‘VMEbus. 


bits [7:6]time-out 


0051.2 us 
01128 us 
10 3.2us 
11 none 








bits (5:4] VMEbus Bus Request time-out 
This field determines how long the MVIC waits to acquire the 
‘VMEbus before asserting a Bus Error on the VMEbus or halting 
the DMA transfer. 


bits [S:t]time-out 
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0.01638.4 us 
0 1409.6 us 
10 128us 
11 none 


bits [3:2]VMEBus Request Level 


bits [3:2] Bus Request Level 
000 
ord 
10 2 
113 


bit [1] VMEbus Arbiter mode 
When set to 1, the VMEbus will arbitrate the bus requests in 
a round-robin manner. Otherwise a fixed priority scheme will 
be used. 


bit (0]Reserved 


VMEbus Slave Configuration Register (offset OxFES) 





bits (31:28]Reserved 
bits [27:24]A32 VME Slave Window Size 


bits (27:24] _A32 Slave Window Size 


0 16MB 
132MB 
2128 MB 
3. 256 MB 
4512 MB 








The board will respond if the A32 enable bit is set and : 
Window Start Address + Size > VME Addr >= Window Start Address 
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bits [23:16] A32 Slave Base Address 
Determines the starting VMEbus address the board will respond 
to in A32 slave mode. These 8 bits correspond to bits [51:24] 
of VME A32 address. 


bits [15:0]Reserved 


(Note that all "Reserved" bits shall not be modified) 





- Cut here for patch_kmem.c - 





” 
* Pw 11/93, User access to kmem 
" 


include <fent1.h> 
include <errno.h> 

include <sys/file.n> 
Winclude <sys/types.h> 
#include <sys/mman.h> 


define DATATYPE unsigned int 


void main(argc, argv) 
int arge; 
char *argv{]: 
€ 
int kmem; 
caddr_t pageptr; 
DATATYPE *ptr, oldvalue; 
unsigned addr, value; 


/* Check args */ 
if (arge < 2) ( 
usage: 
printf("%s <hex address> [<hex value>]\n",argv{0]}; 
exit (0); 


sscanf(argv(1],"tx*,&addr); 
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if (arge == 3) /* value to set */ 
sscanf(argv(2], *8x",avalue) ; 





"be 
* open kmem 
ay 
if ((kmem = open(*/dev/kmem*,O_RDWR)) < 0) ( 
perror(*open error”); 
exit (errno); 


y 
* map it, at a page boundary 
sa 
if ((pageptr = mmap(0L, PAGESIZE, PROT_READ|PROT_WRITE, 
MAP_SHARED, kmem, (off t) (addr & PAGEMASK)}) 





(eaddr_t)-1) ¢ 
perror(*mmap error"); 
exit (errno): 
13 
ptr = (DATATYPE *)((unsigned int)pageptr + (addr & PAGEOFFSET)}; 


” 
* Operations on kmem 
+ 
oldvalue = *ptr; 
if (argc == 3) /* value to set */ 
printé(*Oxtx : Oxtx --> Oxdx\n",addr, oldvalue, *ptr= (DATATYPE) value); 
else 
printé("Oxx : Oxtx\n*,addr,oldvalue) ; 


ys 
* unmap kmem 
*/ 
if (munmap(pageptr, PAGESIZE) == -1) ( 
perror(*munmap error"); 
exit(errno) ; 








Cut here ~ 
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7.7 Removing NEXUS Driver 





TECHNICAL NOTE No 131-00 








‘SUBJECT: Removing NEXUS driver on the 10MP 





BOARD: THEMIS 10MP 











DATE: Oct 2, 195 











Since release 1.7, THEMIS solaris 24vme NEXUS driver is released in 
the pkgadd format. Some problems may occur if you are trying to run 
"pkgadd -d /dev/rmt/0” (package installation) on a system to which 
the VME NEXUS driver was installed using the former tvme-install 
install script. 


‘The workaround is to follow those instructions: 


1. Boot single user. 





2. “rem_drv tyme’ 
“device busy”. 


~ ignore any error messages that might result, such as 


3. “rem_dry mvc" - - again, ignore any error messages, 


4. Restore /etc/system from /etc/system-bak. /etc/system.bak was created 
by the tvme-install script. If other changes have been made to /etc/system 
since tvme-install was run, then the lines related to the tvme driver should 
be removed manually, since restory from /etc/system/bak will result in 
loss of those changes. The relevant lines are: 


moddir: /kernel /usr/kernel /themis 
forceload: dev/tvme 
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5. Restore /etc/driver_classes or /kernel/drv/classes from the backup file, 
which will name /etc/driver_classesbak or /kernel/drv/classes.bak. 
Again, if those files have bveen modified since tvme-install was run, the 
lines related to the tvme driver should be removed manually, The relevant 
line is: 





“THEMIS,vme"vme 


6, Restore /etc/devlink.tab from /etc/devlink.tab.bak. Once again, be sure the 
file hasn’t been modified since tvme-install was run, or else remove the lines. 
related to tvme manually. The relevant lines are: 


type=ddi_pseudo;name=mvc;minor=amvc0 

type=ddi_pseudo;name=vmememminor=a32d32-_vme32d32 
type=ddi_pseudo;name=vmemem;minor=a24d32___yme24d32 
type=ddi_pseudo:name=vmemem;minor=al6d32___- yme16d32. 
type=ddi_pseudo;name=vmememsminor=a32d16 _vme32d16 
type=ddi_pseudo;name=vmememsminor=a24d16 __vme24d16 
type=ddi_pseudo;name=vmememsminor=al6d16 _ vme16d16 





7. Reboot the system using the ‘-r" flag 


8. Run the “pkgadd -d /dev/rmt/0” command to install the new package. 
Then reboot the system using the ‘-r’ flag. 


9. Run the “pkginfo -1” to make sure the package was installed correctly. 
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7.8 Determining Speed of MBus Modules 





TECHNICAL NOTE No 132-00 








‘SUBJECT: Determining Speed of Ross MBUS modules. 
BOARD: THEMIS 10MP 

0.8. all 

Hardware rev: all 














DATE: Oct §, 1995 











The proper way of determining the Frequency of an MBUS CPU module is to 
use the module-info command under OBP. Unfortunately, in the 10MP, 
module-info is printing a wrong value of the CPU frequency. The value is 
displayed using 2 digits only. So the upper digits will not be displayed. Sya, 
you have a 100MHZ module. Then module-info will reuten “00 Hinz” 


‘There is no special registers on the Ross modules, that tell users what is the 
frequency of the module they are using. OBP is timing a software loop to 
determine it. 


The only way to find the frequency is to check the label on the Ross module 
MBUS connector. The first number of the left is giving the value (66, 90, 100,...). 
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7.9 Memory Error Message 





TECHNICAL NOTE No 134-00 








‘SUBJECT: te0: memory error waming message. 
BOARD: THEMIS 10MP 
0.S.: Solaris 2.4 











Hardware rev: all 
DATE: August 1, 1995, 














Under Solaris 2.4, and when the I0MP is making intensive SBUS 
and VME activity, the message: 
1e0: memory error 


will pop-up at random occasions. This is due to the Lance 
(Ethernet) driver that is unable to access memory because 
of the system activity. 


This problem is solved by a Sun patch, that deals with the 
latency time the driver can wait before getting access to 
memory. See below for a readme of that patch 

To install that patch: 


# cd 101979-06 
#./installpatch 
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To check if this patch is already installed: 
# showrey -p 
To get that patch, or in case of problems: 
THEMIS Technical Support 
3185,Laurelview Court Fremont,CA 94538 USA 
(510)252-0870 


(510)490-5529 
support@themis.com 


Patch-ID# 101979-06 
Keywords: ethemet driver memory le0 le ethernet aui hang 
Synopsis: SunOS 5.4: le driver fixes 

Date: Aug/22/95 

Solaris Release: 24 

‘SunOS Release: 5.4 

Unbundled Product: 

Unbundled Release: 

Topic: SunOS 5.4: le driver fixes 

Bugld's fixed with this patch: 1145294 1161058 1171562 1177296 
Changes incorporated in this version: 1177296 

Relevant Architectures: sparc 


Patches accumulated and obsoleted by this patch: 102444-01 


Patches which conflict with this patch: 
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Patches required with this patch: 
Obsoleted by: 

Files included with this patch: 

Jkemel /drv/le 

Problem Description: 

1177296 ethernet interface hangs on large transfers over AUI but not TP 
This is a recrank of 101979-05. -05 rev was missing 1177296 fix. 

(from 101979-05) 

1177296ethernet interface hangs on large transfers over AU! but not TP 
(from 101979-04) 

1161058 Under many collisions, get erroneous led: No carrier message 
Under many collisions, get erroneous le0: No carrier message 


(from 101979-03) 





1171562 Getting "led: Memory error!” when copying large file across network 
$510 with dual processors running 23 with OLDS 2.0.1 installed, gets le0: 
Memory error when copying large files over the network. A hard hang then 
occurs. This eliminates console error message that existed with 101979-02. 
(from 101979-02) 

1171362 Getting “led: Memory error!” when copying large file across network 
$510 with dual processors running 23 with OLDS 2.0.1 installed, gets le0: 


Memory error when copying large files over the network. A hard hang then 
occurs. 
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(from 101979-01) 


1145294 classic 4.1.3C freeze 5-10Mins on receipt of Giant Packet fro1 
ARAL e 


Problem is seen on active networks where the network interface on Classic's, 
LX's, Sparcstations 5 and 20 (based on MACIO) may hang and ignore incoming 
ethernet packets after receipt of a giant packet that is greater than 4096 

bytes. This fix will detect this condition and reset the ethernet interface 

to prevent the interface from hanging, 


Patch Installation Instructions: 





Generic ‘installpatch’ and ‘backoutpatch’ scripts are provided 

within each patch package with instructions appended to this section. 
Other specific or unique installation instructions may also be 
necessary and should be described below 


Special Install Instructions: 


None. 


Instructions to install patch using “installpatch” 








1, Become super-user. 
2. Apply the patch by typing: 
<dir>installpatch <patch-dir> 


where <dir> is the directory containing installpatch, and <patch-dir> is the 
directory containing the patch itself. 


Example: 
# cd /tmp/123456-01 
# ./installpatch, 


3. If any errors are reported, see “Patch Installation Errors” in the Command 
Descriptions section below. 
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Instructions for installing a patch on a dataless client 








1. Before applying the patch, the following command must be executed on the 
server to give the client read-only, root access to the exported /usr file 
system so that the client can execute the pkgadd command: 


share -F nfs -o ro,anon=0 /export/exec/<os_version> /ust 
The command: 


share -F nfs -o ro,root=<client_name> \ 

/export /exec/<os_version>/ust 
accomplishes the same goal, but only gives root access to the client specified 
in the command. 


2. Login to the 





t system and become super-user. 


3. Continue with step 2 in the “Instructions to install patch using installpatch” 
section above. 


Instructions for installing a patch on a diskless client 





** To install a patch on a diskless client, you may either follow the 
instructions for installing on a dataless client (that is, you may. 
logon to the client and install the patch), or you may use the 
following instructions to install the patch while on the server. 


1. Find the complete patch for the root directory of the diskless client. 


2. Install the patch normally, but add the command option -R<path> to the 
command line. <path> should be completely specified. 


Example: 


# ed /tmp /123456-01 
# ./installpatch -R /export/root/client1. 
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Instructions for backing out a patch using “backoutpatch” 








1. Become super-user. 
2. Change directory to /var/sadm /patch: 
ed /var/sadm/patch 
3. Backout patch by typing: 
<patch-id> /backoutpatch <patch-id> 
where <patch-id> is the patch number. 
Example: 


ed /var/sadm/patch 
# 123456-01 /backoutpatch 123456-01 


4. If any errors are reported, see “Patch Backout Errors” in the Command 
Description section below: 


Instructions for backing out a patch on a dataless client 





1. Give the client root access to /usr as specified in the installpatch section 


2. Logon to the client and follow backoutpatch instructions as specified above. 


Rev. Date: 9/20/96 Adteanced Configuration of MP 7-99 





7-100 


Instructions for backing out a patch on a diskless client 











* To backout a patch on a diskless client, you may either follow they 
structions for backout on a dataless client (that is, you may 
logon to the client and backout the patch), or you may use the 
following instructions to backout the patch while on the server. 





1. Find the complete path for the root directory of the diskless client. 


2. Backout the patch normally, but add the command option -R <path> to the 
command line. <path> should be completely specified. 


Example 


# cd /export /root/clientl /var/sadm/patch 
# ./123456-01/backoutpatch -R /export/root/client! 123456-01 


Instructions for identifying patches installed on system: 





Patch packets that have been installed can be identified by 
using the -p option. To find out which patches are installed on 
a diskless client, use both the -R <dir> option and the -p 
option, where <dir> is the fully specified path to the client's 
root directory. 

ed. /tmp /123456-01 

# /installpatch -p 

#./installpatch -R /export/root/clientl -p 


Also note that the command “showrev -p" will show the patches installed 
on the local machine, but will not show patches installed on clients. 
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Command Descriptions 





NAME 


installpatch - apply patch package to Solaris 2.x system 
backoutpatch - remove patch package, restore previously saved files 


SYNOPSIS 


installpatch [-udpV] [-S <service>] <patch number> 
backoutpatch [-FV] [-S <service>] <patch number> 


DESCRIPTION 


These installation and backout utilities apply only to 

Solaris 2.x associated patches. They do not apply to Solaris 
1.x associated patches. These utilities are currently only 
provided with each patch package and are not included with 
the standard Solaris 2.x release software. 


OPTIONS 
installpatch: 


-u unconditional install, turns off file validation. Allows the patch 
to be applied event if some of the files to be patched have been 
modified since original installation. 

-4 Don’t back up the files to be patched. This measn that the 
patch CANNOT BE BACKED OUT. 

-p _Printa list of the patches currently applied 

-V Print script version number 

+S _<service> Specify an alternate serviec (e.g. Solaris_2.3) for 
patch package processing references, 

-R <dir> Specify an alternate package installation root. Most 
useful for installaing patches on diskless clients while logged 
on to the server. 
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backourpatch: 
-f_ force the backout regardless of whether the patch was 
superseded 
-V___ print version number only é 
-S __<service> Specify an alternate service (e.g. Solaris_2.3) for 
patch package processing references. 
-R <dir> Specify an alternate package installation root. Most 


useful for removing patches on diskless clients while logged 
on to the server. 


DIAGNOSTICS 


Patch Installation Errors: 


Error message: 
The prepatch script exited with return code <retcode>. 
Installpatch is terminating. 


Explanation and recommended action: The prepatch script supplied 
with the patch exited with a return code other than 0. Run a 
script trace of the installpatch and find out why the prepatch 
had a bad return code. Fix the problem and re-run installpatch. 


To execute a script trace: 
# sh -x .installpatch . > /tmp/patchout 2>&1 


The file /tmp/patchout will list all commands executed by 
installpatch. You should be able to determine why your prepatch 
script failed by looking through the /tmp/patchout file. If 

you still can't determine the reason for failure, contact 

customer service. 





Error message: 
The postpatch script exited with return code <retcode>. 


Backing out patch. 
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Explanation and recommended action: The postpatch script 


provided with the patch exited with an error code other 

than 0, and the patch has not previously been applied. 
Installpatch will execute backoutpatch to return the system ~ 
to its pre-patched state. Create a script trace of the 
installpatch (see above) and find out why the postpatch script 
failed. Correct and re-execute installpatch, If you are 

unable to determiae why the postpatch script failed, 

contact customer service. 


Error message: 
The postpatch script exited with return code <retcode> 
Not backing out patch because this is a re-installation. 
The system may be in an unstable state! 
Installpatch is terminating, 


Explanation and recommended action: The postpatch script 
provided with the patch exited with an error code other 
than 0, Because this is a re-installation of a patch, 
installpatch will not automatically backout the patch 
You may backout the patch manually using the backoutpatch 
command, then generate a script trace of the installpatch 
as described above. Find out why the postpatch failed, 
correct the problem, and re-install the patch. If you are 
unable to determine why the postpatch script failed, contact 
customer service. 


Error message: 
Patch <patch-id> has already been applied. 


Explanation and recommended action: This patch has already been 
applied to the system and no additional patch packages would 
be added due to a re-installation. If the patch has to be 
reapplied for some reason, backout the patch and then 
reapply it 


Error message: 


Symbolic link in package <pkg> 
Symbolic links can’t be part of a patch. 
Installpatch is terminating. 
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Explanation and recommended action: The patch was incorrectly 
built. Contact customer service to get a new patch. 

Error message: 
This patch is obsoleted by patch <patch-id> which has already 
been applied to this system. Patch installation is aborted. 


Explanation and recommended action: Occasionally, a patch 
is replaced by a new patch which incorporates the bug fixes 
in the old patch and supplies additional fixes also. At 
this time, the earlier patch is no longer made available 
to users. The second patch is said to “obsolete” the 
first patch. However, it is possible that some users 
may still have the earlier patch and try to apply it to 
a system on which the later patch is already applied. 

If the obsoleted patch were allowed to be applied, the 
additional fixes supplied by the later patch would no 
longer be available, and the system would be left in an 
inconsistent state. This error message indicates that 
the user attempted to install an obsoleted patch. There 
is no need to apply this patch because the later patch 
has already supplied the fix. 








Error Message: 
None of the packages to patch are installed on this system. 


Explanation and recommended action: The original packages for 
this patch have not been installed and therefore the patch 
cannot be applied. The original packages need to be installed 
before applying the patch. 


Error message: 
This patch is not applicable to client systems. 


Explanation and recommended action: The patch is only 
applicable to servers and standalone machines. Attempting 
to apply this patch to a client system will have no effect on 
the system. 
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Error message: 
The -S and -R arguments are mutually exclusive. 


Explanation and recommended action: You have specified both a- 
non-native service to patch, and a package installation root. 
These two arguments are mutually exclusive. If patching a 
non-native usr partition, the -S option should be used to patch 
all clients using that service. If patching a client's root 
partition (either native or non-native), the -R option 
should be used. 


Error message: 
The <service> service cannot be found on this system. 


Explanation and recommended action: You have specified a non- 
native service to patch, but the specified service is not 
installed on your system. Correctly specify the service 
when applying the patch. 


Error message: 
The Package Install Root directory <dir> cannot be found on this 
system 


Explanation and recommended action: You have specified a 
directory that is either not mounted, or does not exist on 
your system. Specify the directory correctly when applying 
the patch 


Error message: 
The /usr/sbin/pkgadd command is not executable. 


Explanation and recommended action: The /ust/sbin/pkgadd 
command cannot be executed. The most likely cause of this 
is that installpatch is being run on a diskless or dataless 
client and the /usr file system was not exported with 
root access to the client. See the section above on 
“Instructions for installing a patch on a diskless or 
dataless client”. 
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Error message: 
<patch-id> packages are not proper patch packages, 


Explanation and recommended action: The patch directory 
supplied as an argument to installpatch did not contain the 
expected package format. Verify that the argument supplied 
to installpatch is correct. 


Error message: 
The following validation error was found. 
<validation error(s)> 


Explanation and recommended action: Before applying the patch, 
the patch application script verifies that the current 
versions of the files to be patched have the expected 
fes checksums and attributes. If a file to be patched has 
been modified by the user, the user is notified of this 
fact. The user then has the opportunity to save the 
file and make a similar change to the patched version. 

For example, if the user has modified /etc/inet/inetd.conf 
and /etc/inet /inetd.conf is to be replaced by the patch, 
the user can save the locally modified /etc/inet//inetd.conf 
file and make the same modification to the new file 

after the patch is applied. After the user has noted all 
validation errors and taken the appropriate action for 

each one, the user should re-run installpatch using 

the “-u" (for “unconditional’) option. This time, the 

patch installation will ignore validation errors and 

install the patch anyway. 





Error message: 
Insufficient space in /var/sadm/patch to save old files, 


Explanation and recommended action: There is insufficient 
space in the /var/sadm patch directory to save old files. 
The user has two options for handling this problem: 
(1) generate additional disk space by deleting unneeded 
files, or (2) override the saving of the old files by 
using the "-d" (do not save) option when running installpatch. 
However if the user elects not to save the old versions of 
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the files to be patched, backoutpatch CANNOT be used. 


‘One way to regain space on a system-is to remove the 

save area for previously applied patches. Once the user 

has decided that it is unlikely that a patch will be 

backed out, the user can remove the files that were saved 

by installpatch. The following commands should be executed 
to remove the saved files for patch xxxxxx-yy. 





ed /var/sadm/ patch /xx70xx-yy 
rm -r save/* 
rm oldfilessaved 


After these commands have been executed, patch xxxxxx-yy can 
no longer be backed out. 


Error message: 
Save of old files failed. 


Explanation and recommended action: Before applying the patch, 
the patch installation script uses cpio to save the old 
versions of the files to be patched. This error message 
means that the cpio failed. The output of the cpio 
would have been preceded this message. The user should 
take the appropriate action to correct the cpio failure. 

‘A common reason for failure will be insufficient disk 
‘space to save the old versions of the files. The user 

has two options for handling insufficient disk space: 

(1) generate additional disk space by deleting unneeded 
files, or (2) override the saving of the old files by 

using the "-d" option when running installpatch. However 
if the user elects not to save the old versions of the 

files to be patched, the patch CANNOT be backed out. 





Error message: 
Pkgadd of <pkgname> package failed with error code <code> 
See /tmp /log.<patch-id> for reason for failure 


Explanation and recommended action: The installation of one of 
patch packages failed. Installpatch will backout the patch 
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to leave the system in its pre-patched state. See the log file 
for the reason for failure. Correct the problem and 
re-apply the patch. 


Error message: 
Pkgadd of <pkgname> package failed with error code <code>. 
Will not backout patch...patch re-installation. 
Warning: The system may be in an unstable state! 
See /tmp/log.<patch-id> for reason for failure. 


Explanation and recommended action: The installation of one of 
the patch packages failed. Installpatch will NOT backout the 
patch. You may manually backout the patch using backoutpatch, 
then re-apply the entire patch. Look in the log file for the 
reason pkgadd failed. Correct the problem and re-apply the 
patch 


Patch Installation Messages: 








Note: the messages listed below are not necessarily considered errors 
as indicated in the explanations given. These messages are, however, 
recorded in the patch installation log for diagnostic reference. 


Message: 
Package not patched: 
PKG=SUNXxxx 
Original package not installed 





Explanation: One of the components of the patch would have patched a 
package that is not installed on your system. This is not 
necessarily an error. A Patch may fix a related bug for several 
packages. Example: suppose a patch fixes a bug in both the 
online-backup and fddi packages. If you had online-backup installed 
but didn’t have fddi installed, you would get the message 


Package not patched: 


PKG=SUNWbf 
Original package not installed 
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This message only indicates an error if you thought the package 
was installed on your system. If this is the case, take the 
necessary action to install the package, backout the patch (if 

it installed other packages) and re-install the patch. + 


Message: 
Package not patched: 
PKG=SUNxxx 
ARCH=Xxxxxxx. 
VERSION =xxxxxxx 
Architecture mismatch 





Explanation: One of the components of the patch would have patched a 
package for an architecture different from your system. This is not 
necessarily an error. Any patch to one of the architecture specific 
packages may contain one element for each of the possible 
architectures. For example, Assume you are running on a sundm, If 
you were to install a patch to package SUNWear, you would see the 
following (or similar) messages: 


Package not patched: 
PKG=SUNWear 
ARCH=sparc sundc 
VERSION=11.5.0,REV=2.0.18 
Architecture mismatch 


Package not patched: 
PKG=SUNWear 
ARCH=sparc.sundd 
VERSION=11.5.0,REV=2.0.18 
Architecture mismatch 





Package not patched: 
PKG=SUNWear 
ARCH=sparcsunde 
VERSION=11.5.0,REV=2.0.18, 
Architecture mismatch 


Package not patched: 
PKG=SUNWear 
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ARCH=sparcsunt 
VERSION=115.0,REV=2.0.18 
Architecture mismatch 


‘The only time these messages indicate an error condition 
is if installpatch does not correctly recognize your architecture. 


Message: 
Package not patched: 
PKG=SUNxxxx 
ARCH= 10x 
VERSION=nxxxxxx 
Version mismatch 


Explanation: The version of software to which the patch is applied is 
not installed on your system. For example, if you were running Solaris 
53, and you tried to install a patch against Solaris 5.2, you would 
see the following (or similar) message: 


Package not patched: 
PKG=SUNWestt 
ARCH=spare 
VERSION=10.0.2 
Version mismatch 


This message does not necessarily indicate an error. If 
the version mismatch was for a package you needed patched, either 
get the correct patch version or install the correct package version. 
Then backout the patch (if necessary) and re-apply. 


Message: 
Re-installing Patch. 


Explanation: The patch has already been applied, but there is 
at least one package in the patch that could be added. For 
example, if you applied a patch that had both Openwindows and 
‘Answerbook components, but your system did not have Answerbook 
installed, the Answerbook parts of the patch would not have 
been applied. If, at a later time, you pkgadd Answerbook, you 
could re-apply the patch, and the Answerbook components of the 
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patch would be applied to the system. 


Message: 
Installpatch Interrupted. a 
Installpatch is terminating. 


Explanation: Installpatch was interrupted during execution 
(usually through pressing *C). Installpatch will clean up 
its working files and exit. 


Message: 
Installpatch Interrupted. 
Backing out Patch. 


Explanation: Installpatch was interrupted during execution 
(usually through pressing SC). Installpatch will clean up 
its working files, backout the patch, and exit. 


Patch Backout Errors: 





Error message: 
prebackout patch exited with return code <retcode> 
Backoutpatch exiting. 


Explanation and corrective action: the prebackout script 
supplied with the patch exited with a return code other 
than 0. Generate a script trace of backoutpatch to determine 
why the prebackout script failed. Correct the reason for 
failure, and re-execute backoutpatch. 


Error message: 
postbackout patch exited with return code <retcode> 
Backoutpatch exiting,” 


Explanation and corrective action: the postbackout script 
supplied with the patch exited with a return code other than 
0. Look at the postbackout script to determine why it failed 
Correct the failure and, if necessary, RE-EXECUTE THE 
POSTBACKOUT SCRIPT ONLY. 
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Error message: 
Only one ser 





ice may be defined. 

Explanation and corrective action: You have attempted to specify 
‘more than one service from which to backout a patch. Different 
services must have their patches backed out with different 
invocations of backoutpatch. 


Error message: 
The -S and -R arguments are mutually exclusive. 


Explanation and recommended action: You have specified both a 
non-native service to backout, and a package installation root. 
These two arguments are mutually exclusive. If backing out a 
patch from a non-native usr partition, the -S option should be 
used. If backing out a patch from a client's root 
partition (either native or non-native), the -R option 
should be used. 





Error message: 
The <service> service cannot be found on this system. 


Explanation and recommended action: You have specified a non- 
native service from which to backout a patch, but the 
specified service is not installed on your system. Correctly 
specify the service when backing out the patch 


Error message: 
Only one rootdir may be defined. 


Explanation and recommended action: You have specified more than 
one package install root using the -R option. The -R option 
may be used only once per invocation of backoutpatch. 


Error message: 
The <dir> directory cannot be found on this system. 
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Explanation and recommended action: You have specified a 
directory using the -R option which is either not mounted, 
of does not exist on your system. Verify the directory name 
and re-backout the patch. 


Error message 
Patch <patch-id> has not been successfully applied to this system, 


Explanation and recommended action: You have attempted to backout 
a patch that is not applied to this system. If you must 
restore previous versions of patched files, you may have to 
restore the original files from the initial installation CD. 


Error message: 
Patch <patch-id> has not been successfully applied to this system 
Will remove directory <dir> 


Explanation and recommended action: You have attempted to back 
out a patch that is not applied to this system, While the 
patch has not been applied, a residual 
/vat/sadm/patch/<patch-id> (perhaps from an unsuccessful 
installpatch) directory still exists. The patch cannot be 
backed out. If you must restore old versions of the patched 
files, you may have to restore them from the initial 
installation CD. 


Error message: 
This patch was obsoleted by patch <patch number>. 
Patches must be backed out in the order in 
which they were installed. Patch backout aborted, 


Explanation and recommended action: You are attempting to backout 
patches out of order. Patches should never be backed-out out 
of sequence. This could undermine the integrity of the more 
current patch. 


Error message: 


Patch <patch-id> was installed without backing up the original 
files. It cannot be backed out. 
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Explanation and recommended action: Either the -d option of 
installpatch was set when the patch was applied, or the save 
area of the patch was deleted to regain space. As a result, the 
original files are not saved and backoutpatch cannot be used. 
The original files can only be recovered from the original 
installation CD. 


Error message: 
pkgrm of <pkgname> package failed return code <code>. 
See /var/sadm /patch/<patch-id> /log for reason for failure. 


Explanation and recommended action: The removal of one of 
patch packages failed. See the log file for the reason for 
failure. Correct the problem and run the backout script again. 


Error message: 
Restore of old files failed. 


Explanation and recommended action: The backout script uses the 
‘cpio command to restore the previous versions of the files 
that were patched. The output of the cpio command should 
have preceded this message. The user should take the 
appropriate action to correct the cpio failure. 


KNOWN PROBLEMS: 


On client server machines the patch package is NOT applied 

to existing clients or to the client root template space. 

Therefore, when appropriate, ALL CLIENT MACHINES WILL NEED 
‘THE PATCH APPLIED DIRECTLY USING THIS SAME INSTALLPATCH 
METHOD ON THE CLIENT. See instructions above for 

applying patches to a client. 


A bug affecting a package utility (eg. pkgadd, pkgrm, pkgchk) 
could affect the reliability of installpatch or backoutpatch 
which uses package utilities to install and backout the patch 
package. It is recommended that any patch that fixes package 
utility problems be reviewed and, if necessary, applied before 
other patches are applied, Such existing patches are: 
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100901Solaris 2.1 
101122Solaris 22 
101331Solaris 23 5 


SEE ALSO 
pkgadd, pkgchk, pkgrm, pkginfo, showrev, cpio 


Rev. Date: 3/20/96 Addoanced Configuration of 1OMP 7S 


7 





7.10 VME Bus Interrupt Problem 


716 





TECHNICAL NOTE No 135-00 








‘SUBJECT: VME Bus error and interrupt problem on 10MP/solaris2.4 





BOARD: THEMIS 10MP 
O.S.: Solaris 2.4 








Hardware rev: all 











[DATE: October 1, 1995 





‘There is problem in the way Solaris 2.4 is handling VME bus 
errors for HyperSparc MBUS modules. VME bus errors could result 
in a system crash, when made from a user program. The normal 
behavior is to send a signal to the task, not to crash the 

system, 


‘Themis has released a new VME nexus driver(version 1.7) which is 
fixing that problem. 


Also, the nexus driver was modified so as not to TACK VME interrupts 
which are masked on the 10MP. The problem was to be seen in the 
following situation: 


There is an SBUS interrupt level 3. The 10MP needs to determine 
if the interrupt is a VME or SBUS interrupt. To do so, it is 

making an [ACK cycle at level 3 on the VME. If the [ACK cycle 
times-out, then the 10MP considers this was an SBUS interrupt. 

But suppose, that in the same time there was a local SBUS interrupt 
level 3 on the 10MP, there was also a VME interrupt level 3, from and 

to 2 other boards. Then, before version 1.7 of the VME nexus driver, 

the 10MP was going to LACK that interrupt. This was causing some kind 
of problems as the IOMP was IACKing an interrupt not meant to it. Also 
the 10MP would print a message, saying it got a Spurious interrupt. 


The conclusion is that, it is wise to mask all VME interrupts not 
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used by the 10MP, as this will suppress the VME LACK cycle during 
SBUS interrupt. This will also increase interrupt latency for 

SBUS interrupts. 

To check the version of the nexus driver: 


# pkginfo -1 THEMISvme 


To mask interruopts on the 10MP, please see TN107 
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7.11 10MP OBP PROM 





TECHNICAL NOTE No 138-00 








‘SUBJECT: New 10MP O8P prom (Watchdog resetSolaris 112 boot problem) 
‘BOARD: THEMIS 10MP 
(0.8: Solaris 1.1.2 and 2.4 











Hardware rev: all 
DATE: October 18, 1995 














‘The 10MP OBP prom 2.12.4 is solving 2 different problems on the 10MP: 


1. Under Solaris 1 
to boot solaris 1.1.2. 





- Early ROSS modules (Freq<100MHZ) will not be able 


2. Under Solaris 2.4: - If users “break into” OBP, using the L1(STOP)-A 
keyboard keys, or the VT100 break key, then they won't to able to return to 
OBP by using the OBP “go” command. Instead they will get a “no program 
active” error message. Also, after the machine is halted, the message 
“Watchdog reset” will be printed. 





7118 Advanced Configuration of 10MP Rev. Date: 3/20/96 





7.12 New 10MP OBP PROM Reset 
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‘TECHNICAL NOTE No 139-00 








‘SUBJECT: New 10MP OBP prom (Watchdog reset/Solaris 112 boot problem) 
BOARD: THEMIS 1OMP 
0.8.: Solaris 1.1.2 and 2.4 











Hardware rev: all 


DATE: October 18, 195 














The 10MP OBP prom 2.12.4 is solving 2 different problems on the 10MP: 


1. Under Solaris 1. 
to boot solaris 1.1.2. 





- Early ROSS modules (Freq¢100MHZ) will not be able 


2. Under Solaris 2.4: - If users “break into” OBP, using the L1(STOP)-A 
keyboard keys, of the VT100 break key, then they won't to able to return to 
OBP by using the OBP “go” command. Instead they will get a “no program 
active” error message. Also, after the machine is halted, the message 
“Watchdog reset” will be printed. 
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7.13 Using TTYC OBP PROM 
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‘TECHNICAL NOTE No 145-00 











‘SUBJECT: Using the TTYC OBP prom 





BOARD: THEMIS 10MP_ 





(0.8: Solaris 2.x 





Hardware rev: all 





DATE: Nov, 1995 











‘THEMIS provides a special OBP prom on the 10MP, for customers 
who wants to be able to use ttyc as a console. 


After you set the ttye and ttyd jumpers accordingly (from 
Keyboard/Mouse to TTYC and TTYD, see 10MP user's manual, 


J2501 from 1-2 to 2-3 
J2502 from 1-2 to 2-3) 


you need to consider the following: 


Solaris 2.X will boot under the new OBP without any OS modifications. 
The system will need to reconfigure devices, so after the new prom is 
installed, the system should be booted using ‘boot -r'. However, 

Solaris wil not push the correct streams drivers onto ttyc by default: The 
result will be that the terminal modes will not echo correctly or perform 
canonical input and output processing until the system is in multi-user mode 
and at a login prompt. Once reaching a login prompt, login as root and 

edit the file /etc/iu.ap. Changes the lines referencing 2s to the following: 


zs 0 3 _ Idterm ttcompat 
2s 131072 131073 Idterm ttcompat 


This will cause the system to autopush the appropriate streams modules 
on ttye and ttyd. 
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‘VMEbus device drivers written for Solaris environments, It is the intention of 

‘Themis Computer to fully support users who wish to write their own VME 
device drivers that would function on Themis SPARC 1OMP platforms. To aid these 
users and to illustrate the specific features of the VMEbus architecture, Themis 
provides a number of sample device drivers. Themis provides the complete source 
code and the necessary configuration files for these drivers. 


T he software interface provided for the 10MP platform fully supports standard 





 vmeintr: is a sample driver provided by Themis Computer to illustrate the 
vectored interrupt mechanism of the VMEbus. The vmeintr driver relies on the 
driver configuration files to specify the interrupts it should handle, Each instance 
of the driver registers the interrupts with the system, Through the ioctls 
implemented by the driver. the user can generate interrupts and send them to the 
appropriate driver instances. The interrupt generator and the interrupt receiver 
need to run on different computers. 





+ vmedvina: is a sample driver provided by Themis Computer to illustrate the use 
of Direct Virtual Memory Access within a device driver, The user can ask the 
driver to allocate a DMA region on the VMEbus. The driver allocates all the 
necessary resources to Support a DVMA transfer to this region, The driver also 
implements mechanisms by which the user program can writer to or read from the 
DYMA region 





« simpledma: is a sample driver provided by Themis Computer to illustrate the use 
of Direct Memory Access within a device driver. It is a simplified version of the 
standard vmedma driver. This driver is mainly intended for programmers writing 
device drivers that perform DMA operations on the VMEbus. 


‘The source and binary versions of these drivers can be found in the directory 
JopuTHEMISvmeddrv. System programmers that are writing device drivers for 
‘VMEbus devices are strongly encouraged to go through the source code of these 
sample drivers. Along with the information found in Chapter 5, Writing Device 
Drivers, these sample drivers offer a good insight into the design and development of 
device drivers for VMEbus devices. The drivers can be modified without any 
restrictions. 


‘The sample device drivers are not essential for the normal operation of the SPARC 
1OMP system, When the THEMISwme package is installed, the drivers and theit 
configuration files are copied to the disk, but are not installed on the system, After 
rebooting the machine, the user may choose to install these drivers. 


Scripts have been provided to perform the above tasks. The install sample 
scripts copies the drivers (as they are packaged) to the /kernel/drv directory. 
It then installs the drivers on the system, creates the files under /dev and 
copies the header files into the /usr/include/themis directory. The 
remove.sample script undoes all the installation done by the install script. You 
are strongly urged to carefully review the scripts before executing them, 


If you need to make any changes to the drivers, you need to compile the 
drivers after the changes. After that you can copy the newly built driver object 
files to the /kernel /drv directory. You can install the new drivers on the 
running system by first executing the cem_drv command and then the add_drv 
command, 


The remove sample script removes the sample drivers from the running 
system. The script deconfgures the drivers from the kernel and remove the 
driver object files from the /kernel/drv directory. 
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Manual Pages A 





his section contains the manual pages for all the drivers provided by 
Themis Computer. Manual pages are available for the standard nexus 
and DMA drivers as well as the sample drivers. Online copies of the 
manual pages for the standard drivers can be found in the standard manual 
pages location. Online copies of manual pages for the sample drivers can be 
found in the /opt/THEMISvme/man directory 
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evme(4) "ES AND NETWORK INTERFACES evme(4) 


NAME 
“THENTS,vme",tvme - Nexus driver for VME bus 


symorsts 
‘THEMIS, mme9f, £3£££000 


DESCRIPTION . 

‘The tvme device driver is a VuEbus Nexus Driver designed 
especially for Themis Computer‘s SPARCLOMP platforms. The 
driver is configured to be the bus for the 
class “vme". All leaf drivers that spec 
‘yme" will be attached to the tvme driver. 
provides support for all VMEbus operations, including VME 
interrupt processing, Direct Virtual Memory Access (DVMA) on 
the VMEbus, mapping of registers on the Vibus to kernel 
space etc 


















‘The tvme driver provides these feature: 





= Master access in VMEA24 mode 
= Slave access in VMEA32 mode 


~ Direct viet 





Memory Access ([DVMA) on the VMEbus 





- Block Transfer in Master and Slave modes 





‘The interface between the VMEbus and the MBus is provided by 
the Fujitsu MB86986 MBus to VMEbus Interface Controller 
(vic). The tyme driver supports a single instance of MVIC. 
The driver initialises the controller for operation and han- 
dles asynchronous faults from the controller. User access to 
features of the MVIC, including the Direct Memory Access 
engine is provided by the mve(7) driver. 








The tvme driver supports the vectored interrupt mechaniam of 
the Vibus architecture. All vme devices that generate 
interrupts are expected to provide the ‘interrupts’ property 
in the device configuration file. The tvme driver supports 
SPARC interrupt priorities 2,3,5,7,9,11 and 13. The driver 
handies interrupt vectors 0 t2'255! 








‘The driver fully supports Direct Virtual Memory Access on 
the Vibus. All the OVMA requests from vme device drivers 
are completely handled by the driver. A DYMA request can be 
made for a maximum of 1024 Kilobytes at a time. 
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FILES 
kernel /dry/tyme 


SEE ALSO 
vvme (4) 


driver.con£ (4) 
‘Themis Computer SPARCLOMP Technical Manual 


‘Themis Computer SPARCLOMP Software Manual 
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vmedna {4} DEVICES AND NETHORK INTERFACES vmedna(4) 


NAME 
vmedna - Themis driver for Direct Memory Access 


syvopsts 
fd = open { */dev/vmedmad’, o_aDwR); 


err = ioctl (£4, command, arz}; 


DESCRIPTION 
On Themis Computer's SPARCLOMP platforms, the Fujitsu 
MBa6986 MBus to VMEbus Interface Controller (MviC) features 
aa high performance DMA contr: that provides bi- 
directional  menory-to-Mebus Menory Access 
transfers. The vmedma driver provides user programs a 








to the Direct Memory Access engine of the MVIC. The OMA 
engine can suppor: ali these transfers: - memory to 
vebus = Visbus to memory = memory to memory 


‘The vmedma driver is designed to provide a powerful mechan- 

ign for highly sett involving the memory and 
uniform across the dif- 

Ferene. uaiiane platforms available from Themis Compucer, 

‘The vmedma driver is configured ag ac! 

nexus drive: 

forms. 











The driver supports the open(2) (2), docet(2) and 
poll(2) system calis. The commands implemented by the driver 
are accessed through the ioctli systen call. the 
VIOCOMACOPY ioctl command implements the basic OMA transfer 
capability of the driver. In addition to transfers between 
VMEbus and memory, the vmedna driver also supports transfers 
from memory to memory and VEbus to VMEcus. Depending on the 
capabilities of the hardware platform, these transfers may 
be emulated in software. The VICCGETCAP ioctl command may be 
used to interrogate the capabilities of the underlying 
ardvare mechanism, 




















‘The driver supports the poll(2) system cal! for the event 
POLLRONORM. The polli2) system call blocks till the 
hardware DMA engine is available and returns when the engine 
has completed all queued transfers. However, a successful 
return of poll(2i dces not guarantee that a subsequent 
VIOCDMACOPY command issued by the thread will noc block. 











rOCTLs 
VIOCOMACOPY This command performs a Direct Memory Access 
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transfer are specified in a _vme_dnacopy 
structure. A pointer to this structure is 

passed as the argunen: to the ioctl(2) call 

The user program is suspended till the OMA 

transfer is complete, unless the VF_NOBLOCK i 
flag is specified. The third argument of the 

doctli2) call is a pointer to a 

vme_dnacopy, which is 
<themis/vmedmaio.h> as 
















9 
struct vme_dnacopy ( 
u_int dma_flags: 
void ‘dma_sourc source address */ 
void *dma”: ion address */ 
void *dma_sourc 
void *dnan: in dest, address */ 
wine dma_count; /* byte count */ 
struct vme_dmaresult * 
), maafesuley 7* pointer to result area */ 
struct vme_dmaresult ( 
7+ status of request */ 
ne ned buffer ID */ 
7° errno value */ 
” 
9 


and dadest specify the source 
and destination addresses, respectively, of 
the DMA transfer. If any or both of source 
and destination addresses are 64-bit vizbus 
the dma_sourcehi and dma_desthi 

















eas indicated oth- 
ervise by the dna_flags field. 





‘The dma_flags member contains various 
which are OR'ed together to form the request. 
The first several flags are used to control 
the direction and type of the DMA tranfer. 
‘The interpretation of the dma_source and 
dma_dest members is based on the value of 
dma_flags: 


VE_SvME The A32 VMebus is the 
source of data for the 
transfer. If this flag 
is present, the 
dma_source value is an 
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vP_svwesa 


vP_svmepié 


VF_SvMEDS$ 


ve_pvuE, 


vP_piweze 


VE_ommEss 


A32 VMEbus address. 


The A24 VMEbus is the 
source of data for the 
transfer. 





wigbus is the 
of data for the 
If this flag 
present, the 
is the 
32 bits of the 
address, and 
the dma_sourcehi value is 
igh-order 32 bits of 
VMEbus address 













address 


‘The vugbus source address 
refers to a 064 device 


‘The VMEbus is the desti- 
nation of data for the 
transfer. If this flag 
is presen: the dna_dest 
vaiue is an A}2 VMEbus 
address 








The A2¢ VMEbus is the 
destination of daca for 
fer. If 
present, 
tue is an A24 





‘The AS¢ VMEbus is the 
destination of data for 
the transfer. ff this 
flag is present, the 
dma_des: value is’ the 
lowsordex 32 bits of the 
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vmedma (4) DEVICES AND NETWORK INTERFACES vmedna (4) 


AS4 VMEbus address, and 
the dra_deschi value is 
the high-order 32 bits of 
the AG Wmgbus address. 


VF_DVMEDI6 = The “Vibus destination 
address refers to a D16 
device 

VF_OVMEDSS = The VMEbus destination 


refers to a DSd 





Additional flags are used to control the 
transfer as follows: 





vP_BtT 


VP_NOKAIT If the DMA engine is 
busy, return ; 
error rather than queuing 
the request. 









mn immediacely aft 
queuing or starting the 
reque: ‘The 
vme_draresult area will 

the 


\VF_NOBLOCK 





aus 
ied via SIGIO that 
transfer has com- 
pleted. See below for 
more decails 


\VE_RETAINBUFFER 
User menory buffer(s) are 
locked into memory. Any 
Setup work that can be 
retained between uses of 
the buffer is 
This may make repetit 
transfers of smali sizes 

ficient. Specify 

flag results in 

Le system resources 

being locked up. Hence 

this flag should be used 
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THENZS COMPUTER, 


‘vimedina (4) 





VP_SIGDONE © signal when done {non- 
blocking requests only) 


VE_STGALL, signal all state changes 
inonblocking requests 
only) 


In all cases. the address values must meet 
alignment restrictions. On SPARCLOMP the 
addresses mist be aligned on a 16-byte boun- 
dary. The dma_count menber specifies the 
byte count of the transfer. It must be 
multiple of sixteen bytes. The dma_result 
member points to a structure which is used to 
report information about the OMA transfer. 








f+ status of request */ 
7+ retained buffer ID */ 





yy {BE emme_ereno, 


‘The dmar_status member contains a single 
value which represents the state of the 
transfer: 





request is waiting for 
the DMA engine 


request is in progress 





request has finished nor~ 
sally 

VS_ERROR request has terminated 
due to 








OF 


If a request terminates due to an error, the 
dmar_erzno member will contain an appropriate 
errno value. If the VF_NOBLOCK flag is not 
used, this is the sane as the errno returned 
from the ioctl(2) call 





the VF_RETAINSUFFER flag is used. then 
dmar_bufid wiil contain a buffer handle which 
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should be used in future VIOCDMACOPY calls 
and then released by issuing a VICCRELBUF 
iocth(2) command. When using VF_RETAINEUZFER, 
the dma_result structure pointer is required. 
‘The dnar_oufid value of the structure should 
be initialized to 0 (nuili. In future 
requests using the same buffer or a subset 
thereof, the dnar_bufid value should contain 
the value placed there by che first call, 
When the buffer is no longer needed, VIOCREL- 
BUF must be called with che | recurned 
dmar_bufid value to release the resources the 
retained buffer is using. 


























Tf the VF_NOBLOCK flag is used. chen the 
result area is updated in real time. It is 
important the vme_dmaresult structure be 
allocated in static menory. Depending on the 
mg of the VF_S:GDOONZ and  VF_SIGALL 
SIGIO is sent to the process when the 
status changes (VF_SIGALL) or when the 
request is complete (VF_SIGDONE). When a 
Fequest completes, SIGI0 is sent to the pro- 
cess which made the request. The process 
must then inspect the result area(s) of its 
outstanding request(s) to determine that the 
Fequestis) did complere (with or without 
error}. A SIGIO will be posted for every 
completed “cequest (VF_SIGDONE! or status 
change (VF_SIGALL]. However, signals are not 
quesed, so the driver should inspect all out- 
Standing result areas whenever a SIGIO is 






































received 
VICCRELBUF «Thi ioctl is used release a buffer chat w. 
previously retained by specifying the 


VE_RETAINBUFFER Elag for the VIOCOMACOPY com- 
mand. The argument to the command is the 
dmar_bufid in the vmednaresulz strcuture 
Feturned by a previcus VIOCDMACCPY command, 
Tf the value passed in is not a valid buffer 
handie, EINVAL is retusned. If there is a 
problen releasing the buffer, EFAULT is 
Feturned. A problem releasing the buffer 
indicates an internal driver error and 
should be reported Themis Technical Support. 











VIOCGETCAP «This ioctl is used co determine the capabili- 
ties of the underlying hardware. Note that 


THEMIS COMPUTER Last change: 19 Mar 1996 6 


vmedna (4) 





vmedma (4) 


THEMIS COMPUTER 


vmedna (4) 





R most cases, if the ha: 
of performing a request via DMA then 
represented by the request will be performed 
via other mechanisms. This ensures a common 
interface for user programs across different 
hardware platforms available from Themis Com- 
puter. If the user prograns wis! 
the request to the hardware platform, they 
may do so by using the VI0CSETCAP command, 

















The third argument to the iocti() call is a 
pointer to a vre_dmacap scructure which is 
filled in upon return fram the call. 





struct vme_dmacap ( 
wine dmac_élags; /* flags */ 
lint dmac_align; /+ alignment modulus 
uline dmac_min; 77 minimum effective 








contain zero or 
more of the following flags, OR’ed toget! 





VC_MEXTOMEM © Memozy-to-nemory 
fers are done with a 
ine. Otherwise. 
emulated with 





VC_VMETOVME 


VC_VMETOMEM © VMEbus-to-nemory 
transfers are done with a 
DMA engine. Otherwise, 
they are emulated with 
polled 1/0. 


VC_MEXTOVME — Memory/-to-vMEbus 








transfers are done with a 
DMA engi: ‘Otherwis 
they are emulated with 
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ve_pi6 Dis cransfers 
transfers. Tf this flag 





size 


“ 


is not present and a DIS 
transfer is requested, it 
will be done via polled 
1/0. 


VO_AS4 Vuebus AS4 accesses are 
supported. If this flag 
4s not present and an Asa 
request is made, EINVAL 
will be returned, 


ve_p64 VWizbus D64 accesses are 
supported. If this flag 
is not present and a Dod 
request is made, EINVAL 
will be returned. 


‘The duac_align menber contains the alignment 
oduius hat must be used for che address and 
count when making requests. A misaligned 
Fequest will provoke an BINVAL error return 





The dmac_min member contains a hint as to the 
minim size of a DMA transfer. 

beiow the minimun size may be bet: 
plished ‘otk systen calls 
Fead(2),write(2) esc. 





Example code 


Winclude <scdio.n> 
finclude <sys/types.h> 
include <sys/stat A> 
‘include <fcntl.h> 
#include <unis! 
fined: 











<string.h> 
Sinclude <sys/ertno.h> 
include <stdlib.h> 





#include <themis/vmednaio.h> 
pe 
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* This is a sample program to illustrate the use of the vmedma driver 


* The program transfers 1000 words to VME address 0x72a00000. 





‘* The program thea reads the YME memory and verifies that the 
t data was copied correctly. 


extern char “sys_errlist[]:/* error strings */ 
extern int errno; 


main(int argc. char * argv(]) - 
( 


struct vme_dmacopy dna; /* DMA request structure */ 
int i;/* loop counter */ 

struct vme_dnaresul: ‘dmar = 0;/¢ result structure */ 
int fd;/* VME DMA engine fd */ 

struct timeval starz, end;/* timing */ 

int ns;/* # of reqs started */ 

int err = 


7* error flag */ 
kilobytes copied 
3;/* # of se 

long int * to_buf, * frombuf; /* memory buffers */ 






7* open the DMA engine */ 
Lf ((£d = open(*/dev/vmedmad*, O_RDWR) < 0} 





n 
(void) fprintf(stderr, 
“a: can’t open /dev/vmedzad: 20, 
argv(0], sys_errlist: 
gxte(ays 











eene}) 


/* allocate source memory buffer */ 
if ((to_bug = (long int *)malloc ( 1024 * sizeof(long!)} == NULL) 


c 

(void) fprinté (sta 

‘Ss: can't allocate source memory buffer: 4% 
argv(0], sys_errlist (errno) 

exit(il; 

i} 


2* initialise the memory buffer with numbers from 0 to 1023 */ 
for (i= 0; i < 1024; ise) 
to_buf{i] = 














/* set up the DMA request 
= memory to VMEbus 
*- 32-bit data, 32-bit address 
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” 


stuff */ 


u 


” 


THEMIS COMPUTER 


ma .dma_source = to_buf; /* DMA transfer is from memory to VMEbus 


dma.dma_dest = (void +)0x72a00000, 





/* no 64-bit addresses */ 
7* length of data transfer * 





sult = NULL; /* we don’t bother about the result area * 








ma.dma_tlags = VE_DVME; /* destination is VME: no other special 


if ( iocelied, viocomacopy, sda) < 0) ( 

(void) fprintf(stderr, 

"$s: can’t do DMA transfer: 450, 
argv(0], sys_errlist [errno]; 

free ( to_buf); 

exit (Li; 


free ( to_buf); 


/* allocate destination memory buffer */ 





€ ((feomibuf = (long int *)matloc ( 1024 * sizeof{long))) 


« 

(void) fprinez (stderr, 

"Qs: can’t allocate destination memory buffer: 430, 
argv(0], sys_errlist{errno]); 


(2)s 











Lise the memory buffer with numbers from 0 to 1023 */ 
0; i < 2024; e+) 
=u 





J get up the DMA request 
‘+ Viebus to memory 

> 32-bit daca, 32-bit address 

no BLT 

= do not retain but 
7 

gma.dna_source = (void *) 0x72a90000; 
Gma.dma_dest = (void *) frombuf; /* DMA transfer is from VMEbus 








fers 





/* no 64-bit addresses */ 


dma.dma_sourcehi = dma.dma_desthi = 0, 
/* length of data transfer + 


@ma.dma“sount = 1024 * sizeof (Long: 





@ma.dma_result = NULL; /* we don't bother about the result area * 
dma, dma_flags = VF_SvME; /* source is VME; no other special stuff 


if (ioctLtfd, vrccoMACopy, gdma} < 0) 
C 
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(void) fprinté (stderr, 

‘$s: can’t do OMA transfer: %30, 
azgv(0], sys_errlist [errno] ): 

free ( from_buf}; 

exit(1 

y 





7+ now compare what we read with what we wrote */ 
for (i= 0; i < 1024; ire) 
if ( frompuf{il t= i) 
printé 

Daca check error at offset ‘x: got tx, expected 4x0, 
i, frombuflil, i) 








Js clean up and return */ 
free ( from_but); 
close ( fal; 


FILES 
dev /vmecmad 


Juse/include/thenis/ymectlio.h 
/kernel/dzv/vmedna.cont 

SEE ALSO 
evme(7) 
vmet4) 
deiver.cont (4) 
‘Theis Computer SPARCLOMP User Manual 
qhenis Computer SPARCLOMP Software Manual 
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vmedvma{ 4 DEVICES AND NETWORK INTE! 


NAME 
vmedvma - Themis sample driver for 
Access 





Virtual Memory 


syNoPsts 
Winclude <themis/vmeduma.h> 


f@ = open ( */dev/vmedvmad", O_RDWR); 


err = ioctl{ fd, cmd, arg); 


DEscRIPTron 
vmedvma is a sample driver provided by Themis Computer to 
illustrate the ‘use of Direct Memory Access within a device 
Griver, The driver is provided along with the source code to 
help developers writing vme device drivers. The driver will 








function only on Themis Computer platforms. 


the device 
calls as needed. In 
calls, the driver 
supports the close{) systen call to close the driver 
instance. Through the ioctl(} commands provided, the us 

Gan allocate a number of DVMA regions on the VMESus. The 
user can write to or read from these regions and free them. 








TOCTL INTERFACE 
‘The third argument to jecti() is 
vme_dvmacopy, which is defined in 








struct vme_dvmacopy ( 
int size; 
int ids 
caddr_t addr, 
int of fser, 








vi 


‘The size and offset parameters is specified by the applica. 
tion and is not modified by the driver. The addr parames 
is used as a read/write paramecer and can be changed by the 
application. The id merker is used to identity the DYMA 
region and should not be modified by the application. 








VOMALALLOCATE allocates a DMA region. The input parameter 
size specifies the size of the region to be allocated. The 
gziver allocates a DvMA region and Sets the id parameter 
The address of the DVMA region is returned in the adds 
parameter. If a DMA regicn can not be allocated because of 
memory constraints, the ioctli) call fails and sets errno &5 
ENOMEM. The id parameter is used to identify the allocated 
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vmedema id! 


DYMA region for all further operations on the region, Any 
other board on the VME chassis can access the allocted DVMA 
region using the addr parameter. 


VOMAPREZ frees the DVMA region specified by the id parame- 
ter. All resources allocated for the region will be freed. 





VOMA_WRITE copies data from user memory to the DYMA region. 
The Id parameter mist specify a value previously returned by 
a VOMAALLOCATE. The addr parameter specifies the user 
memory location from where the daca will be copied. The size 
parameter specifies the amount of data to be copied. The 
offset paramete: specifies the location from the beginning 
of the DVMA region where user data will be written to. The 
sum of size and offset must not be greater than the size of 
the allocated region. 











VDMA_READ copies daca from the DVMA region to user memory. 
‘The id parameter must specify a value previously returned by 
a VOMAALLOCATS. The addr parameter specifies the 
memory location intc which data will be copied. The 
Parameter specifies the amount of data to be copied. 
specifies the iocazion from the begi: 

om from where the data will be read. 

set must not be gre 
the allocated region. 




















Example code : 





‘This program allocati 
Ze then writes = 
character time. It then ri 
them with what was written. 


a DVMA region that is 26 bytes long. 
phabets inzo the region on 
ds the daca and compares 











include <stdio.h> 
include <sys/sypes.h> 
include <fentl.h> 


include <themis/ymedvma.h> 


maint) 
C 
int td; 
int count; 
‘struct vme_dvmacopy dma_req: 
struct vme_dvmacopy dna read; 
struct vme_dvmacopy dma_weite; 
char aiphat26]; 
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char beta(26}: 


7+ open the device */ 
LE ((£d = open{*/dev/vmedvma0*, O_RDWR! <0) 
c é 
perror(*can‘t open /dev/vmedvmad"): 
exit(L): 





» 


/* allocate a DVMA region */ 





dma_raq.size = 26; 
LE (ioctl (éd, VOMA_ALLOCATS, Sdma_req) != 0) 
t 

perror{"In allocating DVMA") 

close( fd); 

return(-1 





) 


printf (‘Allocated a DVMA region id : 4d, at virtual sbus address : & 
x0, dma_req.id, dma_req.add=) 


i ge the dna write request */ 
@ma_write.id = dea_req.id, 
dmalwrite size = L7 











/* weite the alphabet charactez by character */ 
for ( count = 0; count < 26; count +=) 
C 





alpha(count) = ‘a/ + count; 
dma_vrite.addr = alpha-count; 
dmalweite offse= = count; 








Af (oce2(€4, VORAWRETE, ecma_vr 


perror{*in writing *); 
lose(fdl ; 
retura(-1); 
) 

) 


/* initialise the dma read requ 








if (4ectL(fd, VONA_READ, gdma_read) != 0) 
c 
perror(*In reading * 
closettd); 
reture(-L) 
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/* read the DVMA memory and compare with what was written * 
for { count = 0; count < 26; count ++) 

if ( alpha(count] != beta(count] } 

printé{*Data mismatch: wrote ¥c, Read $c0, 

alphafcount], beta(count]) 


) 





7* clean up and ret: 
close(fd) : 
recura(0); 


7 


FILES 
(dev /vmedvmad 


Juse/include/thenis/vmedvma.h 
keene! /drv/vmedvma.cont 


SEE ALSO 
‘evme (7) 


vme (4) 
driver.conf(4) 
‘Themis Computer SPARCLOMP Technical Manual 





‘Themis Computer SPARCLOMP Software Manua! 





THst 
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NAME 
vmeintr - Themis sample driver for vMebus intersupts 


swvopsts 
Winclude <themis/vmeintr.h> 


fd = open ( /dev/vmeintrd , 


err = iocth{ fd, SENOINTR, arg); 








DESCRIPTION 
vmeintr is a sampl to 
illustrate the vectored interrupt mech: VEbus 





code to help 


The driver is provided along with the sou 
1@ driver will func- 


developers writing vme device drivers. 
tion only on Themis Computer platforms 





The driver provides a mechanism by which an in! 
generated on the VMgbus. This interzupt can be received by 
any other VME board on the VMEbus. The system that generates 
the interrupt would not receive it. The vmeintr drive: 
relies on the driver configuration files to specify the 
interrupts it should handle. Each instance of the driver 
Fegisters che interrupts with the syszem. Through the ic: 
implemented by the driver, the user can ge: 

and send them to the appropriate driver ins 


























= progran invokes the driver by 
iasuing the appropriate ioctl 

A to the openi} and icc! 
supports the close() systen call to close the driver 
instance. 






TOCTL INTERFACE 
‘The third argument to ioctl() is a poi 
vme_intz_vect, which is defined in <themis/vmeint: 
typedef struc! 


‘ 

int vecto: 

int priority: 

dong timeout: 7* used only for GETINTROATA */ 
Jvmeincrvect : 
vector specifies the vitbus interrup 
Between 0 - 255. griority specifies the Viibus interrupt 
priority and has a value between 1 - 7. Ciceout is used only 
for (the GETINTRDATA command and specifies the time in 
microseconds. 














vector and has a value 








REQINTRSIGNAL prepares the driver to receive the specif, 
interrupt from another: board on the VME chassis. 
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priority - vector pair should be a valid value specified in 
the configuration file. An invalid value will result in an 
error of EINVAL being returned. 





SENDINTR sends the specified interrupt on the VMgbus. This 
interrupt will be received by ary board on the VMEbus that 
has the particular interrupt: enabled. 








GETINTROATA waits for the specified interrupt. If the inter- 
rupt has already been received, the cal! will return immedi- 
ately, Otherwise the calling process will be blocked till 
the interrupt is received or till timeout microseconds 
ellapse, whichever occurs earlier. If the timeout is speci- 
fied as -1, the calling process will be blocked till the 
interrupt is received. 














‘Typically two systems sharing the same VME chassis are 
needed to use the vmeintr driver. One of the systems is used 
to generate the interrupts and another is used to receive 
the intezrupss, 








Example code ( interrupt receive: 





include <stdio.h> 
binclude <sys/types.h> 
include <fontl.h> 





Winclude <themis/vmeints.h> 


ine €4; 
vme_intr_vect vect; 
vme_intr_vect vect_recvd; 


if (fd = open(*/dev/vmeintro", O_RDWR!)<0) 
c 
perror(*can’t open /dev/vmeintr0*); 
exitiL); 
d 


/* assume argv(1] specifies the vector and argv(2] specifies 
the priority 
a7 


vect.vector = atoi ( argvfil_); 
vact priority = atoi ( argv(2l ; 
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enable the interrupt 
if (ioctl (fd, REQINTRSIGNAL, Evect) < 0) 


perror(*In enabling interrupts‘); 
close( fd); 
Fecura(-L); 

) 


7 wait for the interrup: */ 
Printé(*Waiting for interrupt : 4d. 
vect_recvd. timeout = 30 * 1000 * 1000; /+ wait for 30 seconds */ 
it (loctlifd, GETINTRDATA, avect_recvd) < 0) 

C 








if(errno == ETzME) 
Princé(*Tineout occured, Interrupt was probably not ger 
error{"In receiving interrupts’); 

close (fd) ; 

return(-2); 


eated.0) 





y 


Jt print the received interrupt 
peinc’(*Received vector 4d at priority0, vect_recvd.vector, 
vect_recvd.priority); 











¢* clean up and return * 
close( fd); 
return(0); 











Example code { intersupt gene: 
include <stdio.h> 
Winclude <sys/types.h> 
Sinclude <fent2.h> 


include <themis/vmeintr.h> 


int fa: 
vme_ints_vect vect; 


if ((£a = open(*/dev/vmeinte0*, O_WRONLY!)<0) 
{ 
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perror{ ‘can't open /dev/vmeintr0"); 
exitil}: 


/* assume argv(1] specifies the vector and argv(2] specifies 
the priority 

” 

vect.vector = atoi ( argvfl] }; 

vect priority = atoi ( argv[2] 





{* send the interrupt */ 
print €("Sending interrupt : td ...0, vect.vector 
££ (iocel(£d, SENDINTR, Evect) <0) 

ni 





error(*in sending interrupts); 
close(£d); 
return (-1 





/* clean up and return */ 
close( fd): 
Feturn(0); 


PILES 
/dav/vmeintsd 


/usr/include/themis/ymeints.h 


/kernel/drv/vmeintr cont 


SEE ALSO 
‘evme (7) 


vme 4) 
dziver.cont ia) 

Themis Computer SPARCLOM? User Manual 
Themis Computer SPARCLOMP Software Manual 
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NAME 
vmemen - Device driver for VMEbus access 
seNoPsts 
fd = open ( */dev/vmextare, O_ADHR}; 
DESCRIPTION 





‘The vmemem driver provides a standard way to access thi 
VwEpus from user processes. The driver creates device spe- 
cial files under the /dev directory. These files support 
open(), close), readi), write(} and smap{! calls to access 
the VMEbus. The type of access to the VMEbus is indicaced by 
the name of the device file: 











(dev/vme?2d3}2__- 32 bic address, 32 bit daca /dev/vme22d15 
32 bit address, 16 bit daca /dev/vme2dd32  - 24 bit 
ss, 32 bit data /dev/vme2ddié = 24 bit address, 16 
bit data /dev/vmezsd32 0-16 address, 32 bit data 
ddevivmeléd1s = ‘16 bit address, 16 bit daca 




















The user program accesses any part of the vitEbus address 
space by opening the device file and accessing it at a par- 
ticular offset. For example, to access address location 
0x72000000 of the 32 bit VME space, the user can open the 
file /dev/vme32d32 and seek to offset 0x72000000. For effi- 
cient access, the user can map the VMEbus address space into 
the user address space by using the amapi) systen call. 














‘This program accesses a specific region in the 
space. It initialises the regicn and reads the values back. 





finclude <stdio.h> 
include <sys/types.h> 
Winclude <unistd.h> 





7+ open the device +/ 
if ((Ed = open(*/dev/vme32d32", O_RDWRI}<9) 
c 
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Berror{ "can’t open /dev/vmemen"}: 
exitill: 
y 
iseek( fd, 0x72000000, seEx_seT); 
value = 0; 
for { count = 0; count < 1024; count ++) 
of {int)} t= sizeof(int) } 
iseek( £4, 0x72000000, SeEx_seT); 
for { count = 0; count < 1024; count ++) 
c 
if ( read ( £2, avalue, sizeof(int)} != sizeof(int) } 
perror("In reading’); 
= 07 
peintgi"Error at: tx, read $d instead of zero0. 
9x72000000 + (count * sizeof(int)}, vaiuel; 
ey 
close( fa); 
return{0): 
) 
FILES 
(dev /vme32432 
/dav /vme32415 
(dev /vme2 4232 
/dev/vme24dis 
sdev/vmet6d32 
/dev/vmel6d26 


(eernel/drv/vmemen. cont 


SEE ALSO 
tume{7) 
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me (4) 
driver.cont(4) 
‘Themis Computer SPARCLOMP Technical Manual 


‘Themis Computer SPARCLOMP Software Manual 
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NAME 
simpledma - Simplified sample driver for Direct Memory 
Access 

symopsts 
fd = open { */dev/simpledma2", O_RDWR); 
err = ioctl 1fd, command, arg 

DESCRIPTION 


simpledna is a sample driver provided by Themis Computer to 
illustrate the use of Direct Memory Access from drivers 
VitEbus devices. The driver is a che 
more powerful vmedma driver. provided along 
with the source code. On Themis Computer's SPARCLKEr and 
SPARC5/64 platforms, the Newbridge SC764 VMzsus Controller 
(Scv64) features a a high performance OMA controller that 
provides bi-directional memory-to-‘MEbus Direct Memory 
cess data transfers. The VMEbus nexus 

Of functions chat can be used by Vit 
Direct Memory Access opera 


























supports the open(2), close(2), icetl(2) and 
poll(2) system calls. The commands implemented by the driver 
are accessed through the iocel(2! system call. 
VICCDMACOPY ioctl command implements the basic DMA trans: 
capability of the driver. tn addition to transfers between 
VMEbus and memory, the simpledma driver also supports 
transfers from menory to memory and VMEbus to VMEbus. 
Depending on the capabilities of the hardware platform, 
these transfers may be emulated in software. The VIOCGETCAP 
ioctl command may be used to interrogate the capabilities of 
the underlying hardware mechanisn. 

















‘The driver supports the poll(2) system call for the event 
POLLADNORM. The polli2) system call blocks till the 
hardware OMA engine is available and returns when the engine 
completed all queued transfers. However, a successful 
urn of poli(2i does not guarantee that a subsequent 
OMACOPY command issued by the thread will not block. 











TOCTLS 

VIOCDMACOPY «This command performs a Direct Memory Access 
transfer between the specified address lo 

tions. The ‘source address, destination 

address, size of the transfer and the type of 
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transfer are specified in a vme_dracopy 

ucture. A pointer to this st i 
passed as the argument to the ioctli2) call. 
The user program is suspended till the DMA 
transfer is complete, unless the VF_NOBLOCK 
flag is specified. The third argument of the 
focei(2) call is a pointer to a struct 
vme__dmacopy. which is defined = in 
<themis/vmedmaio.h> as 




















9 
struct vme_dmacopy ( 
uint dma_flags; /* flags */ 
void ‘dnalsource; /* source address */ 
void "dna_dest; it fon address */ 
void ‘dma_sourcehi: /* in source address */ 
void tdma_desthi; /7 in dest. address */ 
u_int dmamcount; /* byte count */ 
struct vme_dmaresult * 
dna_result; 7* pointer to result area */ 
vw 
struct vme_dnaresult ( 
int dmar_status; /* status of request */ 
yoid ‘dmar_bufid; /* retained buffer ID */ 
{nt dmar_errnc; | /* erzno value */ 
ds 
9 


dma_source and dmadest specify the source 
and destination addresses, respectively, of 
the DMA transfer. If any or both of source 
ard destination addresses are 64-bit VMEbus 
the dma_sourcehi and dma_desthi 
onding higher bits of the 
addresses. The addresses are assumed to be 
User virtual addresses unless indicated oth- 
erwise by the dma_flags field. 














‘the dma_flags member contains various flags. 
which ae OR’ed together to form the request. 
The first several flags are used to control 
the direction and type of the DMA tranfer. 
The interpretation of the dma_source and 
dna_dest. members is based on the value of 
dma_élags: 


vE_sime he A32 WWebus is the 
source of data for the 
transfer. I@ this flag 
is presen the 
dma_source valle is an 
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ve_svmez4 


ve_svmEsé 





VP_SvMEDS4 


‘ve_pvMe24 


VF_OvMEs4 





A32 Vwebus address 


A24 VMEbus is the 
of data for the 
If this flag 

is presenc, ‘the 

dma_source value is an 

A24 VMEbus address. 


The AS4 Vwmbus is the 
source of data for the 
transfer. If this flag 
is present the 
dma_sourse value is the 
32 bits of the 








the fightorder 3 32 bits of 
the Ai Vmebus address. 


YMEbus source address 





‘The VMEbus source address 
refers to a 084 device. 


‘The VMEbus is the desti- 
naticn of data for the 
transfer. If this flag 

the dna_dest 





WMEbus address 


The A64 VuEbus is the 
destination of data for 
the transfer. If this 
flag is present, the 
dna_dest value is’ the 
low-order 32 bits of the 
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AS4 Vebus address. and 
the dma_desthi value is 
the highvorder 32 bits of 
the a4 Ywebus address. 





VE_DVMEDIG == The_-“VMEbus_—_ destination 
address refers to a D1S 








VP_OVMED64 = The VMEbus 
address refers to a 36a 
device 


Additional flags are used to control the 
transfer as follows 


VE_BLT Use block transfer mode 











esuSY 
han queuing 


\VP_NOBLOCK ely after 
‘ssarting the 
The 
area will 
when the 
Addi- 
tionally the user pro- 
cess can request to be 
ied via SIGIO chat 
transfer has com- 
See below for 
ails. 











VF_SIGDONE = signal when done (non- 
blocking requests only) 


\VP_STGALL signal all state changes 
(nonblecking requests 
only? 


In all cases, the address values must meet 
alignment restrictions. On SPARCS/6d_ the 
addresses must be aligned on a S-byte boun- 
dary. The dma_count menker specifies the 
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byte count of the transfer. It must be a 
multiple of eight bytes. The dma_result 





struct vme_dnaresult ( 
int dmar_status; /* status of request */ 
void *dnar_bué: 7" revained buffer ID */ 
int dmar_ereno; 7* ezeno value */ 











The dmar_status menbex contains a single 
value which represents the state of the 
transfer: 


VS_WACTING request is waiting for 
the DMA engine 






VS_INPROG request is in progress 


vS_DONE ¢ finished nor- 





VS_ERROR 3 terminated 
= 

If a request terminates due to an error, the 
dmar_errno member will contain an appropriate 
errno value. If the VF_NOBLOCK flag is not 
used, this is the same as th no returned 
from the ioctl(2) call. 





Tf the VF_NOBLOCK flag is used. then the 
result area is updated in real time. It is 
important the vme_cmaresult structure be 
allocated in static memory. Depending on the 
getting of the VF_SIGDONE and VF_SIGALL 
flags, SIGIO is sent to ch 

status changes (VF_SIGALL) “or when 
request is complete (VF_SIGDONE). 
Fequest completes, SIGr0 is sent to the pro- 
cess which made the request. The process 
must then inspect the result areas} of its 
outstanding request(s) to dezermine that the 
request(s) did. complere (with or withou! 
error). A SIGIO will be costed for every 
ed request (VF_SIGDONE! or status 
change (VF_SIGALL). However, signals are not 
queued, so the driver should inspect all out- 
Standing result areas whenever a SIGi0 is 
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received. 





VIOCGETCAP «This ioctl is used to determine the capabili- 
ties of the underlying hardware. Note that 
in most cases, if the hardware is incapable 
of performing a request via OMA (such as 
memory-to-memory DMA transfer on SPARCS/64) 
then the work represented by the request will 
be performed via other mechanisms. This 
ensures a common interface for user programs 
across different hardware platforms available 
from Themis Computer. =f the user programs 
wish to tailor the request to the herdware 
platform, they may co sc by using the 
VIOCGETCAP command. 








The third argument to the ioctl{) call is a 
pointer to a vme_dmacap structure which is 
filled in upon return from the cait 






























9 
struct vme_dmacap ( 
uint dmac_ftags; /7 flags */ 
ulint dmaclalign; /* alignment modulus */ 
ulint dmaclmi: size */ 
» 
ey 
The dmac_flags member will contain ero oF 
more of the following flags. OR’ed togetht 
Vo_MEYTOMEN 
DMA engine. Otherwise, 
they are emulated with 
potled 1/0 
VC_VMETOVME © YfEbus-to-ViEbus 
transfers are done with a 
DMA engine. Otherwise, 
they are emulated with 
polled 1/0. 
VC_METOMEM — VtEbus-to-memory 
transfers are done with a 
DMA. engine. Otherwise. 
they are emulated with 
polled 1/0. 
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VC_MENTOVME © Menory-to-VttEbus 


Example code : 


include 
include 
include 
include 
include 
include 
include 
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transfers are done with a 
DMA engine, Otherwise, 
they are emilated with 


polled 1/0. 
ve_pts DI6é transfers are DMA 
transfers. If this flag 


is not present and a DiS 
transfer is requested, it 
will be done via polled 








1/0. 
VC_Ags WiEbus A64 accesses are 
supported this flag 





is not present and an A64 
request. is made, EINVAL 
ill be returned. 





vo_p64 Vuebus 06% accesses are 
supported. Tf this flag 
is not present and a 64 
request is made, EINVAL 
will be recurned. 


‘The drac_align menber contains the alignment 
modulus that mist be used for the address and 
count when making A misaligned 
request will provoke an EINVAL error 











The drac_min menber contains a hint as co the 
minimum size of a DMA trani 
below the minimun size may be 
plished via other system 
Fead(2),write(2) etc. 








<atdic.h> 
<sys/types.h> 
<sys/stac.h> 
<fontl.h> 
<unistd.h> 
<signa’.h> 
<time.R> 
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#include <string.h> 
finclude <sys/erzno.h> 


include <stdlib.h> 
include <themis/vmednaio.h> 


rt 
= This is a sample program to illustrate the use of the simpledma dri 


+ The progran transfers 1000 words to VME address 0x72a00000. 
* The program then reads the VME memory and verifies that the 
+ data was copied correctly. 

Md 


i 





External data 
“7 

extern char ‘sys_errlist{1;/* error strings */ 
extern int er=no; 


aaintine exge, char * argvilt 

struct vme_dnacopy dma: /* DMA request structure */ 
int i;/* loop counter */ 

truct vme_dmaresult tdmar = 0;/* result structure */ 
int £a;/* UME DMA engine fd */ 

struct timeval start, end;/* timing */ 

int s;/* ® of reqs started */ 

int err = 0:/* exror flag */ 

double kb; /* kilobytes copied */ 

double secs;/* # of seconds */ 

long int * to_but, * frombut; /* memory buffers */ 





















( open the DMA engine */ 
Le ((fa = open(*/dev/simpledmad", O_ROWR)) < 0} 


c 

(void) fprintéistde: 

can'® open /dev/simpiedmad: 430, 
argv[0], sys_errlist [errno] ); 

exitit); 


a 


{* allocate source memory buffer */ 
Lf ({to_buf = (Long int *)malioe ( 1024 * sizeof(long)!) == NULL) 














t 
(void) fprinté(stders, 
‘Yai can't allocate source memory buffer: $30, 
arqv(0l. sys_e: (errno) 
Ys 
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/* initialise che memory buffer with numbers from 0 to 1023 */ 
for (i = 0; i< 1024; ise) 





“7 


stuff */ 


2) 


to memory */ 
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to_puf til 





7 set up the DMA request 
+ memory to VMEbus 

32-bit data, 32-bit address 
no BLT 
do not retain buffers 


dma_source = to_buf; /* DMA transfer is from memory to vitzbus 
-dma_dest = (void *)0x72a00000; 


‘dma_sourcehi = dma.dma_desthi'= 0; /* no 64-bit addresses */ 
‘dma_sount = 1024 * sizeof(long!; /* length of data transfer * 





dma.dma_result = NULL; /* we don’t bother about the result area * 


ma.dma_flags = VF_DVME; /* destination is VME; no other special 


Lf ( foctl(éd, VzOCDMACOPY, Edma) < 01 ( 

(void) fpr 

"Qs: can't do DMA transfer: %s0, 
argv(0], sys_erslist(errno]); 

free ( to_bufl; 

exitit) 











free { to_but): 


/* allocate destination memory buf 








if ((£rombuf = (long int *jmaltoc ( 1024 * sizecf(longi}) == NUL 


i 

(void) fprines (seder: 

"As: can’t allocate destination memory buffer: %20, 
argv(0], sys_errlist(erzno| 

salsa 








/* initialise the memory buffer with numbers from 0 to 1023 */ 
for (i= 0; £ < 1024; ise) 
from buf[i) = i: 








(+ set _up the DMA request 
‘t+ Vitgbus to memory 

32-bit data, 32-bit address 
no BLT 


do not retain buffers 





.dna_scurce = (void *) 0x72a00000; 
dma_dest = (void *) frombuf; /* DMA transfer is from vwtEbus 


.dma_sourcehi = dma.dma_desthi = 0; /* no S4-bit addresses */ 
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dma. dma_count 
dma.dma_result = NUL 





dma.dma_€lags = VF_SVME; /* source is VME; no other 
” 


if (ioctl(ta, vrocomcory, tdna) < 0) 


(void) fprinté (stderr, 

"Ss: can’t do DMA transfer: 450, 
argv(0l, sys_errlist(erznol i; 

free ( from_bufl; 

exit); 


7+ now compare what we read with what we wrote */ 
for (i = 0; i < 1024; 
if ( frombufli] t= i) 
princé( 

“Data check error at offset $x: got x. expected %x0, 
4, feombufli], i 











J* clean up and return */ 
free ( from_buf) ; 
close ¢ fd; 





FILES 
/dev/simpledmad 





/usr/include/themis/vmectlio.h 


(kernel /dev/simpledma.cont 





SEE ALSO 
evme (7) 


vme (4) 
driver.conf(4) 
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1024 * sizeof(long); /* length of data transfer * 


#* we don’t bother about the result area * 
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